From 37e502cf423a0138d8e0297add7224ca83ce47f3 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 20:10:42 +0800
Subject: [PATCH 01/38] Add file watcher triggers with FA_watch_* actions and
 UI tab

New automation_file.trigger package wraps watchdog observers behind a
TriggerManager singleton. FA_watch_start / FA_watch_stop / FA_watch_stop_all /
FA_watch_list are auto-registered in build_default_registry so triggered action
lists dispatch through the shared executor. Triggers tab in the main window
drives the same lifecycle from the GUI.
---
 automation_file/__init__.py             |  19 ++
 automation_file/core/action_registry.py |   7 +
 automation_file/trigger/__init__.py     |  31 ++++
 automation_file/trigger/manager.py      | 236 ++++++++++++++++++++++++
 automation_file/ui/main_window.py       |   4 +
 automation_file/ui/tabs/__init__.py     |   2 +
 automation_file/ui/tabs/trigger_tab.py  | 171 +++++++++++++++++
 dev.toml                                |   3 +-
 requirements.txt                        |   3 +-
 stable.toml                             |   3 +-
 tests/test_trigger.py                   | 116 ++++++++++++
 tests/test_ui_smoke.py                  |   1 +
 12 files changed, 593 insertions(+), 3 deletions(-)
 create mode 100644 automation_file/trigger/__init__.py
 create mode 100644 automation_file/trigger/manager.py
 create mode 100644 automation_file/ui/tabs/trigger_tab.py
 create mode 100644 tests/test_trigger.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 7419549..6c877d4 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -87,6 +87,16 @@
     TCPActionServer,
     start_autocontrol_socket_server,
 )
+from automation_file.trigger import (
+    FileWatcher,
+    TriggerManager,
+    register_trigger_ops,
+    trigger_manager,
+    watch_list,
+    watch_start,
+    watch_stop,
+    watch_stop_all,
+)
 from automation_file.utils.file_discovery import get_dir_files_as_list
 
 if TYPE_CHECKING:
@@ -186,6 +196,15 @@ def __getattr__(name: str) -> Any:
     "ProjectBuilder",
     "create_project_dir",
     "get_dir_files_as_list",
+    # Triggers
+    "FileWatcher",
+    "TriggerManager",
+    "register_trigger_ops",
+    "trigger_manager",
+    "watch_start",
+    "watch_stop",
+    "watch_stop_all",
+    "watch_list",
     # UI (lazy-loaded)
     "launch_ui",
 ]
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 26d882a..29c2228 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -141,6 +141,12 @@ def _register_cloud_backends(registry: ActionRegistry) -> None:
     register_sftp_ops(registry)
 
 
+def _register_trigger_ops(registry: ActionRegistry) -> None:
+    from automation_file.trigger import register_trigger_ops
+
+    register_trigger_ops(registry)
+
+
 def build_default_registry() -> ActionRegistry:
     """Return a registry pre-populated with every built-in ``FA_*`` action."""
     registry = ActionRegistry()
@@ -148,6 +154,7 @@ def build_default_registry() -> ActionRegistry:
     registry.register_many(_http_commands())
     registry.register_many(_drive_commands())
     _register_cloud_backends(registry)
+    _register_trigger_ops(registry)
     file_automation_logger.info(
         "action_registry: built default registry with %d commands", len(registry)
     )
diff --git a/automation_file/trigger/__init__.py b/automation_file/trigger/__init__.py
new file mode 100644
index 0000000..ac86d36
--- /dev/null
+++ b/automation_file/trigger/__init__.py
@@ -0,0 +1,31 @@
+"""Event-driven triggers — watch local paths and run action lists on change.
+
+Each :class:`FileWatcher` wraps one ``watchdog.Observer`` plus the JSON action
+list to dispatch when a matching event fires. The module-level
+:data:`trigger_manager` owns a registry of named watchers so callers can
+start / stop them from JSON actions or the GUI.
+"""
+
+from __future__ import annotations
+
+from automation_file.trigger.manager import (
+    FileWatcher,
+    TriggerManager,
+    register_trigger_ops,
+    trigger_manager,
+    watch_list,
+    watch_start,
+    watch_stop,
+    watch_stop_all,
+)
+
+__all__ = [
+    "FileWatcher",
+    "TriggerManager",
+    "register_trigger_ops",
+    "trigger_manager",
+    "watch_list",
+    "watch_start",
+    "watch_stop",
+    "watch_stop_all",
+]
diff --git a/automation_file/trigger/manager.py b/automation_file/trigger/manager.py
new file mode 100644
index 0000000..b0af75a
--- /dev/null
+++ b/automation_file/trigger/manager.py
@@ -0,0 +1,236 @@
+"""Watchdog-backed trigger manager.
+
+A :class:`FileWatcher` owns one ``watchdog.observers.Observer`` plus the
+action list to run when a matching filesystem event fires. The module-level
+:data:`trigger_manager` keeps a name -> watcher mapping so the JSON facade
+(``FA_watch_start`` / ``FA_watch_stop`` / ``FA_watch_list``) and the GUI share
+the same lifecycle.
+
+Events are dispatched through the shared :class:`ActionExecutor`, so the
+same JSON action-list shape is used everywhere. Dispatch always happens on
+watchdog's dispatcher thread — the executor's per-action ``try/except``
+prevents a bad action from killing the observer.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers import Observer
+from watchdog.observers.api import BaseObserver
+
+from automation_file.core.action_registry import ActionRegistry
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+_SUPPORTED_EVENTS = frozenset({"created", "modified", "deleted", "moved"})
+
+
+class TriggerException(FileAutomationException):
+    """Raised by the trigger manager on duplicate / missing / invalid watchers."""
+
+
+def _parse_events(events: Iterable[str] | str | None) -> frozenset[str]:
+    if events is None:
+        return frozenset({"created", "modified"})
+    if isinstance(events, str):
+        events = [events]
+    chosen = {item.strip().lower() for item in events if item and item.strip()}
+    unknown = chosen - _SUPPORTED_EVENTS
+    if unknown:
+        raise TriggerException(f"unsupported event types: {sorted(unknown)}")
+    return frozenset(chosen or {"created", "modified"})
+
+
+class _DispatchingHandler(FileSystemEventHandler):
+    """Route watchdog events into an action list on the shared executor."""
+
+    def __init__(
+        self,
+        name: str,
+        events: frozenset[str],
+        action_list: list[list[Any]],
+    ) -> None:
+        super().__init__()
+        self._name = name
+        self._events = events
+        self._action_list = action_list
+
+    def on_any_event(self, event: FileSystemEvent) -> None:
+        kind = event.event_type
+        if kind not in self._events:
+            return
+        file_automation_logger.info("trigger[%s]: %s %s", self._name, kind, event.src_path)
+        from automation_file.core.action_executor import executor
+
+        try:
+            executor.execute_action(self._action_list)
+        except FileAutomationException as error:
+            file_automation_logger.warning(
+                "trigger[%s]: action dispatch failed: %r", self._name, error
+            )
+
+
+class FileWatcher:
+    """One named watchdog observer tied to an action list."""
+
+    def __init__(
+        self,
+        name: str,
+        path: str,
+        action_list: list[list[Any]],
+        *,
+        events: Iterable[str] | str | None = None,
+        recursive: bool = True,
+    ) -> None:
+        resolved = Path(path).expanduser().resolve()
+        if not resolved.exists():
+            raise TriggerException(f"watch path does not exist: {resolved}")
+        self.name = name
+        self.path = resolved
+        self.recursive = bool(recursive)
+        self.events = _parse_events(events)
+        self.action_list: list[list[Any]] = list(action_list)
+        self._observer: BaseObserver | None = None
+
+    @property
+    def is_running(self) -> bool:
+        observer = self._observer
+        return observer is not None and observer.is_alive()
+
+    def start(self) -> None:
+        if self.is_running:
+            return
+        handler = _DispatchingHandler(self.name, self.events, self.action_list)
+        observer = Observer()
+        observer.schedule(handler, str(self.path), recursive=self.recursive)
+        observer.daemon = True
+        observer.start()
+        self._observer = observer
+        file_automation_logger.info(
+            "trigger[%s]: watching %s (events=%s, recursive=%s)",
+            self.name,
+            self.path,
+            sorted(self.events),
+            self.recursive,
+        )
+
+    def stop(self, timeout: float = 5.0) -> None:
+        observer = self._observer
+        if observer is None:
+            return
+        self._observer = None
+        observer.stop()
+        observer.join(timeout=timeout)
+        file_automation_logger.info("trigger[%s]: stopped", self.name)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "path": str(self.path),
+            "events": sorted(self.events),
+            "recursive": self.recursive,
+            "running": self.is_running,
+            "actions": len(self.action_list),
+        }
+
+
+class TriggerManager:
+    """Process-wide registry of :class:`FileWatcher` instances."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._watchers: dict[str, FileWatcher] = {}
+
+    def start(
+        self,
+        name: str,
+        path: str,
+        action_list: list[list[Any]],
+        *,
+        events: Iterable[str] | str | None = None,
+        recursive: bool = True,
+    ) -> dict[str, Any]:
+        with self._lock:
+            if name in self._watchers:
+                raise TriggerException(f"watcher already registered: {name}")
+            watcher = FileWatcher(
+                name=name,
+                path=path,
+                action_list=action_list,
+                events=events,
+                recursive=recursive,
+            )
+            watcher.start()
+            self._watchers[name] = watcher
+            return watcher.as_dict()
+
+    def stop(self, name: str) -> dict[str, Any]:
+        with self._lock:
+            watcher = self._watchers.pop(name, None)
+        if watcher is None:
+            raise TriggerException(f"no such watcher: {name}")
+        watcher.stop()
+        return watcher.as_dict()
+
+    def stop_all(self) -> list[dict[str, Any]]:
+        with self._lock:
+            watchers = list(self._watchers.values())
+            self._watchers.clear()
+        snapshots: list[dict[str, Any]] = []
+        for watcher in watchers:
+            watcher.stop()
+            snapshots.append(watcher.as_dict())
+        return snapshots
+
+    def list(self) -> list[dict[str, Any]]:
+        with self._lock:
+            return [watcher.as_dict() for watcher in self._watchers.values()]
+
+    def __contains__(self, name: object) -> bool:
+        return isinstance(name, str) and name in self._watchers
+
+
+trigger_manager: TriggerManager = TriggerManager()
+
+
+def watch_start(
+    name: str,
+    path: str,
+    action_list: list[list[Any]],
+    events: Iterable[str] | str | None = None,
+    recursive: bool = True,
+) -> dict[str, Any]:
+    """Start a named watcher on ``path`` that dispatches ``action_list``."""
+    return trigger_manager.start(name, path, action_list, events=events, recursive=recursive)
+
+
+def watch_stop(name: str) -> dict[str, Any]:
+    """Stop and remove the named watcher."""
+    return trigger_manager.stop(name)
+
+
+def watch_stop_all() -> list[dict[str, Any]]:
+    """Stop and remove every active watcher."""
+    return trigger_manager.stop_all()
+
+
+def watch_list() -> list[dict[str, Any]]:
+    """Return a snapshot of every registered watcher."""
+    return trigger_manager.list()
+
+
+def register_trigger_ops(registry: ActionRegistry) -> None:
+    """Wire ``FA_watch_*`` actions into a registry."""
+    registry.register_many(
+        {
+            "FA_watch_start": watch_start,
+            "FA_watch_stop": watch_stop,
+            "FA_watch_stop_all": watch_stop_all,
+            "FA_watch_list": watch_list,
+        }
+    )
diff --git a/automation_file/ui/main_window.py b/automation_file/ui/main_window.py
index e54bb4c..1ca5507 100644
--- a/automation_file/ui/main_window.py
+++ b/automation_file/ui/main_window.py
@@ -14,6 +14,7 @@
     LocalOpsTab,
     ServerTab,
     TransferTab,
+    TriggerTab,
 )
 
 _WINDOW_TITLE = "automation_file"
@@ -40,6 +41,8 @@ def __init__(self) -> None:
         self._tabs.addTab(LocalOpsTab(self._log, self._pool), "Local")
         self._tabs.addTab(TransferTab(self._log, self._pool), "Transfer")
         self._tabs.addTab(JSONEditorTab(self._log, self._pool), "JSON actions")
+        self._trigger_tab = TriggerTab(self._log, self._pool)
+        self._tabs.addTab(self._trigger_tab, "Triggers")
         self._server_tab = ServerTab(self._log, self._pool)
         self._tabs.addTab(self._server_tab, "Servers")
 
@@ -76,4 +79,5 @@ def _on_log_message(self, message: str) -> None:
 
     def closeEvent(self, event) -> None:  # noqa: N802  # pylint: disable=invalid-name — Qt override
         self._server_tab.closeEvent(event)
+        self._trigger_tab.closeEvent(event)
         super().closeEvent(event)
diff --git a/automation_file/ui/tabs/__init__.py b/automation_file/ui/tabs/__init__.py
index 57a85a2..2387d86 100644
--- a/automation_file/ui/tabs/__init__.py
+++ b/automation_file/ui/tabs/__init__.py
@@ -13,6 +13,7 @@
 from automation_file.ui.tabs.server_tab import ServerTab
 from automation_file.ui.tabs.sftp_tab import SFTPTab
 from automation_file.ui.tabs.transfer_tab import TransferTab
+from automation_file.ui.tabs.trigger_tab import TriggerTab
 
 __all__ = [
     "AzureBlobTab",
@@ -26,4 +27,5 @@
     "SFTPTab",
     "ServerTab",
     "TransferTab",
+    "TriggerTab",
 ]
diff --git a/automation_file/ui/tabs/trigger_tab.py b/automation_file/ui/tabs/trigger_tab.py
new file mode 100644
index 0000000..8c10eab
--- /dev/null
+++ b/automation_file/ui/tabs/trigger_tab.py
@@ -0,0 +1,171 @@
+"""File-watcher trigger management tab.
+
+Lists active watchers, starts a new one from an inline JSON action list,
+and stops watchers individually or as a batch. All dispatch still goes
+through the shared :class:`ActionExecutor`; this tab is a thin GUI over
+:mod:`automation_file.trigger`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QHeaderView,
+    QLineEdit,
+    QPlainTextEdit,
+    QTableWidget,
+    QTableWidgetItem,
+    QVBoxLayout,
+)
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.trigger import (
+    trigger_manager,
+    watch_start,
+    watch_stop,
+    watch_stop_all,
+)
+from automation_file.ui.tabs.base import BaseTab
+
+_COLUMNS = ("Name", "Path", "Events", "Recursive", "Actions", "Running")
+
+
+class TriggerTab(BaseTab):
+    """Start / stop / list file-system watchers."""
+
+    def __init__(self, log, pool) -> None:
+        super().__init__(log, pool)
+        root = QVBoxLayout(self)
+        root.setContentsMargins(12, 12, 12, 12)
+        root.setSpacing(12)
+        root.addWidget(self._start_group())
+        root.addWidget(self._list_group(), 1)
+        self._refresh()
+
+    def _start_group(self) -> QGroupBox:
+        box = QGroupBox("Start a watcher")
+        form = QFormLayout(box)
+        form.setVerticalSpacing(10)
+        form.setHorizontalSpacing(12)
+
+        self._name = QLineEdit()
+        self._name.setPlaceholderText("unique watcher name")
+        self._path = QLineEdit()
+        self._path.setPlaceholderText("absolute path to watch")
+        self._events = QLineEdit("created,modified")
+        self._events.setPlaceholderText("comma-separated: created,modified,deleted,moved")
+        self._recursive = QCheckBox("Recursive")
+        self._recursive.setChecked(True)
+        self._actions = QPlainTextEdit()
+        self._actions.setPlaceholderText(
+            '[["FA_create_file", {"file_path": "triggered.txt", "content": "hi"}]]'
+        )
+        self._actions.setMinimumHeight(120)
+
+        form.addRow("Name", self._name)
+        form.addRow("Path", self._path)
+        form.addRow("Events", self._events)
+        form.addRow(self._recursive)
+        form.addRow("Actions (JSON)", self._actions)
+        form.addRow(self.make_button("Start watcher", self._on_start))
+        return box
+
+    def _list_group(self) -> QGroupBox:
+        box = QGroupBox("Active watchers")
+        layout = QVBoxLayout(box)
+        layout.setSpacing(8)
+
+        self._table = QTableWidget(0, len(_COLUMNS))
+        self._table.setHorizontalHeaderLabels(_COLUMNS)
+        header = self._table.horizontalHeader()
+        header.setSectionResizeMode(QHeaderView.ResizeMode.Stretch)
+        self._table.verticalHeader().setVisible(False)
+        self._table.setSelectionBehavior(QTableWidget.SelectionBehavior.SelectRows)
+        self._table.setEditTriggers(QTableWidget.EditTrigger.NoEditTriggers)
+        layout.addWidget(self._table)
+
+        row = QHBoxLayout()
+        row.setSpacing(8)
+        row.addWidget(self.make_button("Refresh", self._refresh))
+        row.addWidget(self.make_button("Stop selected", self._on_stop_selected))
+        row.addWidget(self.make_button("Stop all", self._on_stop_all))
+        row.addStretch()
+        layout.addLayout(row)
+        return box
+
+    def _on_start(self) -> None:
+        name = self._name.text().strip()
+        path = self._path.text().strip()
+        raw_events = [event.strip() for event in self._events.text().split(",") if event.strip()]
+        raw_actions = self._actions.toPlainText().strip()
+        if not name or not path or not raw_actions:
+            self._log.append_line("trigger: name, path, and actions are all required")
+            return
+        try:
+            action_list = json.loads(raw_actions)
+        except json.JSONDecodeError as error:
+            self._log.append_line(f"trigger: invalid JSON: {error}")
+            return
+        if not isinstance(action_list, list):
+            self._log.append_line("trigger: action JSON must be an array")
+            return
+        try:
+            snapshot = watch_start(
+                name=name,
+                path=path,
+                action_list=action_list,
+                events=raw_events or None,
+                recursive=self._recursive.isChecked(),
+            )
+        except FileAutomationException as error:
+            self._log.append_line(f"trigger: start failed: {error!r}")
+            return
+        self._log.append_line(f"trigger: started {snapshot}")
+        self._refresh()
+
+    def _on_stop_selected(self) -> None:
+        row = self._table.currentRow()
+        if row < 0:
+            self._log.append_line("trigger: no row selected")
+            return
+        name_item = self._table.item(row, 0)
+        if name_item is None:
+            return
+        name = name_item.text()
+        try:
+            snapshot = watch_stop(name)
+        except FileAutomationException as error:
+            self._log.append_line(f"trigger: stop failed: {error!r}")
+            return
+        self._log.append_line(f"trigger: stopped {snapshot}")
+        self._refresh()
+
+    def _on_stop_all(self) -> None:
+        snapshots = watch_stop_all()
+        self._log.append_line(f"trigger: stopped {len(snapshots)} watcher(s)")
+        self._refresh()
+
+    def _refresh(self) -> None:
+        watchers = trigger_manager.list()
+        self._table.setRowCount(len(watchers))
+        for row, data in enumerate(watchers):
+            self._set_cell(row, 0, data["name"])
+            self._set_cell(row, 1, data["path"])
+            self._set_cell(row, 2, ", ".join(data["events"]))
+            self._set_cell(row, 3, "yes" if data["recursive"] else "no")
+            self._set_cell(row, 4, str(data["actions"]))
+            self._set_cell(row, 5, "yes" if data["running"] else "no")
+
+    def _set_cell(self, row: int, col: int, text: str) -> None:
+        item = QTableWidgetItem(text)
+        self._table.setItem(row, col, item)
+
+    def closeEvent(self, event: Any) -> None:  # noqa: N802  # pylint: disable=invalid-name — Qt override
+        watch_stop_all()
+        super().closeEvent(event)
diff --git a/dev.toml b/dev.toml
index 23230ac..3c15e73 100644
--- a/dev.toml
+++ b/dev.toml
@@ -23,7 +23,8 @@ dependencies = [
     "azure-storage-blob>=12.19.0",
     "dropbox>=11.36.2",
     "paramiko>=3.4.0",
-    "PySide6>=6.6.0"
+    "PySide6>=6.6.0",
+    "watchdog>=4.0.0"
 ]
 classifiers = [
     "Programming Language :: Python :: 3.10",
diff --git a/requirements.txt b/requirements.txt
index 2cb4f68..d6b9100 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -5,4 +5,5 @@ google-auth-oauthlib
 PySide6
 requests
 protobuf
-tqdm
\ No newline at end of file
+tqdm
+watchdog
\ No newline at end of file
diff --git a/stable.toml b/stable.toml
index 91b1b50..992dcaf 100644
--- a/stable.toml
+++ b/stable.toml
@@ -23,7 +23,8 @@ dependencies = [
     "azure-storage-blob>=12.19.0",
     "dropbox>=11.36.2",
     "paramiko>=3.4.0",
-    "PySide6>=6.6.0"
+    "PySide6>=6.6.0",
+    "watchdog>=4.0.0"
 ]
 classifiers = [
     "Programming Language :: Python :: 3.10",
diff --git a/tests/test_trigger.py b/tests/test_trigger.py
new file mode 100644
index 0000000..e52dbea
--- /dev/null
+++ b/tests/test_trigger.py
@@ -0,0 +1,116 @@
+"""Tests for the filesystem watcher trigger manager.
+
+These tests avoid asserting on actual filesystem events — watchdog's
+dispatcher thread is inherently racey across platforms. Instead they cover
+validation, registry wiring, lifecycle, and dict representation.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.trigger.manager import (
+    FileWatcher,
+    TriggerException,
+    TriggerManager,
+    _parse_events,
+    register_trigger_ops,
+)
+
+
+def test_parse_events_defaults_when_none() -> None:
+    assert _parse_events(None) == frozenset({"created", "modified"})
+
+
+def test_parse_events_accepts_string() -> None:
+    assert _parse_events("deleted") == frozenset({"deleted"})
+
+
+def test_parse_events_normalises_case_and_whitespace() -> None:
+    assert _parse_events([" Created ", "MOVED"]) == frozenset({"created", "moved"})
+
+
+def test_parse_events_rejects_unknown() -> None:
+    with pytest.raises(TriggerException):
+        _parse_events(["created", "exploded"])
+
+
+def test_file_watcher_rejects_missing_path(tmp_path: Path) -> None:
+    with pytest.raises(TriggerException):
+        FileWatcher("missing", str(tmp_path / "nope"), [["FA_create_file", {}]])
+
+
+def test_trigger_manager_start_stop_lifecycle(tmp_path: Path) -> None:
+    manager = TriggerManager()
+    snapshot = manager.start(
+        name="t1",
+        path=str(tmp_path),
+        action_list=[["FA_watch_list"]],
+        events=["created"],
+        recursive=False,
+    )
+    try:
+        assert snapshot["name"] == "t1"
+        assert snapshot["running"] is True
+        assert snapshot["events"] == ["created"]
+        assert "t1" in manager
+        listing = manager.list()
+        assert len(listing) == 1 and listing[0]["name"] == "t1"
+    finally:
+        manager.stop("t1")
+    assert "t1" not in manager
+    assert manager.list() == []
+
+
+def test_trigger_manager_rejects_duplicate(tmp_path: Path) -> None:
+    manager = TriggerManager()
+    manager.start("dup", str(tmp_path), [["FA_watch_list"]])
+    try:
+        with pytest.raises(TriggerException):
+            manager.start("dup", str(tmp_path), [["FA_watch_list"]])
+    finally:
+        manager.stop_all()
+
+
+def test_trigger_manager_stop_unknown_raises() -> None:
+    manager = TriggerManager()
+    with pytest.raises(TriggerException):
+        manager.stop("never-registered")
+
+
+def test_trigger_manager_stop_all_clears_everything(tmp_path: Path) -> None:
+    manager = TriggerManager()
+    manager.start("a", str(tmp_path), [["FA_watch_list"]])
+    manager.start("b", str(tmp_path), [["FA_watch_list"]])
+    snapshots = manager.stop_all()
+    assert len(snapshots) == 2
+    assert manager.list() == []
+
+
+def test_trigger_exception_inherits_from_file_automation() -> None:
+    assert issubclass(TriggerException, FileAutomationException)
+
+
+def test_register_trigger_ops_populates_registry() -> None:
+    from automation_file.core.action_registry import ActionRegistry
+
+    registry = ActionRegistry()
+    register_trigger_ops(registry)
+    for name in (
+        "FA_watch_start",
+        "FA_watch_stop",
+        "FA_watch_stop_all",
+        "FA_watch_list",
+    ):
+        assert name in registry
+
+
+def test_default_registry_contains_trigger_ops() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    registry = build_default_registry()
+    assert "FA_watch_start" in registry
+    assert "FA_watch_list" in registry
diff --git a/tests/test_ui_smoke.py b/tests/test_ui_smoke.py
index a94ec39..776096e 100644
--- a/tests/test_ui_smoke.py
+++ b/tests/test_ui_smoke.py
@@ -54,6 +54,7 @@ def test_main_window_constructs(qt_app) -> None:
         "JSONEditorTab",
         "ServerTab",
         "TransferTab",
+        "TriggerTab",
         "HomeTab",
     ],
 )

From af955deee29738e16c85be01261937d3be9cc2f2 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 20:14:35 +0800
Subject: [PATCH 02/38] Add cron scheduler with FA_schedule_* actions and UI
 tab

New automation_file.scheduler package parses 5-field cron expressions
(stdlib-only, supports *, ranges, lists, and step syntax with month / DoW
aliases) and drives a background thread that dispatches each job's action list
on minute-boundary ticks. FA_schedule_add / FA_schedule_remove /
FA_schedule_remove_all / FA_schedule_list are auto-registered alongside the
other FA_* actions. Scheduler tab in the main window drives the same lifecycle
from the GUI.
---
 automation_file/__init__.py              |  21 +++
 automation_file/core/action_registry.py  |   7 +
 automation_file/scheduler/__init__.py    |  35 +++++
 automation_file/scheduler/cron.py        | 140 ++++++++++++++++++
 automation_file/scheduler/manager.py     | 180 +++++++++++++++++++++++
 automation_file/ui/main_window.py        |   4 +
 automation_file/ui/tabs/__init__.py      |   2 +
 automation_file/ui/tabs/scheduler_tab.py | 155 +++++++++++++++++++
 tests/test_scheduler.py                  | 166 +++++++++++++++++++++
 tests/test_ui_smoke.py                   |   1 +
 10 files changed, 711 insertions(+)
 create mode 100644 automation_file/scheduler/__init__.py
 create mode 100644 automation_file/scheduler/cron.py
 create mode 100644 automation_file/scheduler/manager.py
 create mode 100644 automation_file/ui/tabs/scheduler_tab.py
 create mode 100644 tests/test_scheduler.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 6c877d4..5099283 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -82,6 +82,17 @@
 from automation_file.remote.s3 import S3Client, register_s3_ops, s3_instance
 from automation_file.remote.sftp import SFTPClient, register_sftp_ops, sftp_instance
 from automation_file.remote.url_validator import validate_http_url
+from automation_file.scheduler import (
+    CronExpression,
+    ScheduledJob,
+    Scheduler,
+    register_scheduler_ops,
+    schedule_add,
+    schedule_list,
+    schedule_remove,
+    schedule_remove_all,
+    scheduler,
+)
 from automation_file.server.http_server import HTTPActionServer, start_http_action_server
 from automation_file.server.tcp_server import (
     TCPActionServer,
@@ -205,6 +216,16 @@ def __getattr__(name: str) -> Any:
     "watch_stop",
     "watch_stop_all",
     "watch_list",
+    # Scheduler
+    "CronExpression",
+    "ScheduledJob",
+    "Scheduler",
+    "register_scheduler_ops",
+    "schedule_add",
+    "schedule_list",
+    "schedule_remove",
+    "schedule_remove_all",
+    "scheduler",
     # UI (lazy-loaded)
     "launch_ui",
 ]
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 29c2228..cbf9f7b 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -147,6 +147,12 @@ def _register_trigger_ops(registry: ActionRegistry) -> None:
     register_trigger_ops(registry)
 
 
+def _register_scheduler_ops(registry: ActionRegistry) -> None:
+    from automation_file.scheduler import register_scheduler_ops
+
+    register_scheduler_ops(registry)
+
+
 def build_default_registry() -> ActionRegistry:
     """Return a registry pre-populated with every built-in ``FA_*`` action."""
     registry = ActionRegistry()
@@ -155,6 +161,7 @@ def build_default_registry() -> ActionRegistry:
     registry.register_many(_drive_commands())
     _register_cloud_backends(registry)
     _register_trigger_ops(registry)
+    _register_scheduler_ops(registry)
     file_automation_logger.info(
         "action_registry: built default registry with %d commands", len(registry)
     )
diff --git a/automation_file/scheduler/__init__.py b/automation_file/scheduler/__init__.py
new file mode 100644
index 0000000..ec2d481
--- /dev/null
+++ b/automation_file/scheduler/__init__.py
@@ -0,0 +1,35 @@
+"""Cron-style scheduler — run action lists on a recurring schedule.
+
+A :class:`ScheduledJob` pairs a 5-field cron expression (minute hour dom month
+dow) with a JSON action list. The module-level :data:`scheduler` owns a
+background thread that wakes every second, checks which jobs are due, and
+dispatches their action lists through the shared
+:class:`~automation_file.core.action_executor.ActionExecutor`.
+"""
+
+from __future__ import annotations
+
+from automation_file.scheduler.cron import CronException, CronExpression
+from automation_file.scheduler.manager import (
+    ScheduledJob,
+    Scheduler,
+    register_scheduler_ops,
+    schedule_add,
+    schedule_list,
+    schedule_remove,
+    schedule_remove_all,
+    scheduler,
+)
+
+__all__ = [
+    "CronException",
+    "CronExpression",
+    "ScheduledJob",
+    "Scheduler",
+    "register_scheduler_ops",
+    "schedule_add",
+    "schedule_list",
+    "schedule_remove",
+    "schedule_remove_all",
+    "scheduler",
+]
diff --git a/automation_file/scheduler/cron.py b/automation_file/scheduler/cron.py
new file mode 100644
index 0000000..0dc6d87
--- /dev/null
+++ b/automation_file/scheduler/cron.py
@@ -0,0 +1,140 @@
+"""Minimal 5-field cron expression parser (stdlib-only).
+
+Supports ``*``, exact values, ``a-b`` ranges, ``a,b,c`` lists, and ``*/n`` or
+``a-b/n`` step syntax. Fields are, in order: minute (0-59), hour (0-23),
+day-of-month (1-31), month (1-12), day-of-week (0-6, Sunday = 0 or 7). Names
+(``jan``..``dec`` / ``sun``..``sat``) are accepted case-insensitively.
+
+Explicitly *not* supported: ``@yearly`` / ``@reboot`` aliases, ``L``/``W``
+modifiers, seconds. Callers needing that should use a dedicated cron library.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+
+from automation_file.exceptions import FileAutomationException
+
+
+class CronException(FileAutomationException):
+    """Raised when a cron expression cannot be parsed."""
+
+
+_FIELD_BOUNDS = (
+    (0, 59),
+    (0, 23),
+    (1, 31),
+    (1, 12),
+    (0, 6),
+)
+
+_MONTH_ALIASES = {
+    "jan": 1, "feb": 2, "mar": 3, "apr": 4, "may": 5, "jun": 6,
+    "jul": 7, "aug": 8, "sep": 9, "oct": 10, "nov": 11, "dec": 12,
+}  # fmt: skip
+
+_DOW_ALIASES = {
+    "sun": 0, "mon": 1, "tue": 2, "wed": 3, "thu": 4, "fri": 5, "sat": 6,
+}  # fmt: skip
+
+
+def _resolve_alias(token: str, field_index: int) -> str:
+    lowered = token.lower()
+    if field_index == 3 and lowered in _MONTH_ALIASES:
+        return str(_MONTH_ALIASES[lowered])
+    if field_index == 4 and lowered in _DOW_ALIASES:
+        return str(_DOW_ALIASES[lowered])
+    return token
+
+
+def _parse_value(token: str, field_index: int) -> int:
+    resolved = _resolve_alias(token, field_index)
+    try:
+        return int(resolved)
+    except ValueError as error:
+        raise CronException(f"cron: non-numeric value {token!r}") from error
+
+
+def _expand_range(start: int, end: int, step: int, low: int, high: int) -> set[int]:
+    if start < low or end > high or start > end:
+        raise CronException(f"cron: range {start}-{end} outside [{low},{high}]")
+    if step <= 0:
+        raise CronException(f"cron: step must be positive, got {step}")
+    return set(range(start, end + 1, step))
+
+
+def _parse_field(raw: str, field_index: int) -> frozenset[int]:
+    low, high = _FIELD_BOUNDS[field_index]
+    # DoW accepts 7 as an alias for Sunday (0) before range validation.
+    effective_high = 7 if field_index == 4 else high
+    result: set[int] = set()
+    for part in raw.split(","):
+        chunk = part.strip()
+        if not chunk:
+            raise CronException(f"cron: empty chunk in field {field_index}")
+        step = 1
+        if "/" in chunk:
+            base, step_text = chunk.split("/", 1)
+            try:
+                step = int(step_text)
+            except ValueError as error:
+                raise CronException(f"cron: bad step {step_text!r}") from error
+            chunk = base
+        if chunk == "*":
+            result |= _expand_range(low, high, step, low, high)
+            continue
+        if "-" in chunk:
+            start_text, end_text = chunk.split("-", 1)
+            start = _parse_value(start_text, field_index)
+            end = _parse_value(end_text, field_index)
+            result |= _expand_range(start, end, step, low, effective_high)
+            continue
+        value = _parse_value(chunk, field_index)
+        if value < low or value > effective_high:
+            raise CronException(f"cron: value {value} outside [{low},{high}]")
+        if step == 1:
+            result.add(value)
+        else:
+            result |= _expand_range(value, effective_high, step, low, effective_high)
+    if field_index == 4 and 7 in result:
+        result.discard(7)
+        result.add(0)
+    return frozenset(result)
+
+
+@dataclass(frozen=True)
+class CronExpression:
+    """Parsed 5-field cron expression."""
+
+    minutes: frozenset[int]
+    hours: frozenset[int]
+    days: frozenset[int]
+    months: frozenset[int]
+    weekdays: frozenset[int]
+    source: str
+
+    @classmethod
+    def parse(cls, expression: str) -> CronExpression:
+        if not expression or not expression.strip():
+            raise CronException("cron: expression is empty")
+        fields = expression.split()
+        if len(fields) != 5:
+            raise CronException(f"cron: expected 5 fields, got {len(fields)}: {expression!r}")
+        minutes = _parse_field(fields[0], 0)
+        hours = _parse_field(fields[1], 1)
+        days = _parse_field(fields[2], 2)
+        months = _parse_field(fields[3], 3)
+        weekdays = _parse_field(fields[4], 4)
+        return cls(minutes, hours, days, months, weekdays, expression.strip())
+
+    def matches(self, moment: dt.datetime) -> bool:
+        """Return ``True`` when ``moment`` satisfies every field."""
+        weekday = moment.isoweekday() % 7  # Monday=1..Sunday=7 -> Monday=1..Sunday=0
+        return (
+            moment.minute in self.minutes
+            and moment.hour in self.hours
+            and moment.day in self.days
+            and moment.month in self.months
+            and weekday in self.weekdays
+        )
diff --git a/automation_file/scheduler/manager.py b/automation_file/scheduler/manager.py
new file mode 100644
index 0000000..398ffc6
--- /dev/null
+++ b/automation_file/scheduler/manager.py
@@ -0,0 +1,180 @@
+"""Background scheduler for cron-scheduled action lists.
+
+The scheduler thread wakes once a minute (aligned to wall-clock minute
+boundaries), iterates registered jobs, and dispatches each matching job's
+action list through the shared :class:`ActionExecutor`. Dispatch happens on a
+short-lived worker thread so a long-running action cannot block subsequent
+jobs — but callers are still responsible for keeping their action lists
+reasonable in duration.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import threading
+from dataclasses import dataclass, field
+from typing import Any
+
+from automation_file.core.action_registry import ActionRegistry
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+from automation_file.scheduler.cron import CronExpression
+
+
+class SchedulerException(FileAutomationException):
+    """Raised for duplicate / missing / invalid scheduled jobs."""
+
+
+@dataclass
+class ScheduledJob:
+    """One named cron expression paired with an action list."""
+
+    name: str
+    cron: CronExpression
+    action_list: list[list[Any]]
+    last_run: dt.datetime | None = field(default=None)
+    runs: int = field(default=0)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "cron": self.cron.source,
+            "actions": len(self.action_list),
+            "last_run": self.last_run.isoformat() if self.last_run else None,
+            "runs": self.runs,
+        }
+
+
+class Scheduler:
+    """Process-wide scheduler — one background thread drives every job."""
+
+    _TICK_SECONDS = 1.0
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._jobs: dict[str, ScheduledJob] = {}
+        self._thread: threading.Thread | None = None
+        self._stop = threading.Event()
+
+    def _ensure_running(self) -> None:
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._stop.clear()
+        thread = threading.Thread(target=self._run, name="fa-scheduler", daemon=True)
+        thread.start()
+        self._thread = thread
+
+    def _run(self) -> None:
+        last_minute: tuple[int, int, int, int, int] | None = None
+        while not self._stop.is_set():
+            now = dt.datetime.now().replace(second=0, microsecond=0)
+            key = (now.year, now.month, now.day, now.hour, now.minute)
+            if key != last_minute:
+                last_minute = key
+                self._fire_due(now)
+            self._stop.wait(self._TICK_SECONDS)
+
+    def _fire_due(self, moment: dt.datetime) -> None:
+        with self._lock:
+            due = [job for job in self._jobs.values() if job.cron.matches(moment)]
+        for job in due:
+            self._dispatch(job, moment)
+
+    @staticmethod
+    def _dispatch(job: ScheduledJob, moment: dt.datetime) -> None:
+        job.last_run = moment
+        job.runs += 1
+        file_automation_logger.info(
+            "scheduler[%s]: firing at %s (run #%d)", job.name, moment.isoformat(), job.runs
+        )
+        worker = threading.Thread(
+            target=_safe_execute,
+            args=(job.name, job.action_list),
+            name=f"fa-scheduler-{job.name}",
+            daemon=True,
+        )
+        worker.start()
+
+    def add(self, name: str, cron_expression: str, action_list: list[list[Any]]) -> dict[str, Any]:
+        cron = CronExpression.parse(cron_expression)
+        with self._lock:
+            if name in self._jobs:
+                raise SchedulerException(f"job already registered: {name}")
+            job = ScheduledJob(name=name, cron=cron, action_list=list(action_list))
+            self._jobs[name] = job
+            snapshot = job.as_dict()
+        self._ensure_running()
+        file_automation_logger.info("scheduler: added job %r (cron=%r)", name, cron.source)
+        return snapshot
+
+    def remove(self, name: str) -> dict[str, Any]:
+        with self._lock:
+            job = self._jobs.pop(name, None)
+        if job is None:
+            raise SchedulerException(f"no such job: {name}")
+        file_automation_logger.info("scheduler: removed job %r", name)
+        return job.as_dict()
+
+    def remove_all(self) -> list[dict[str, Any]]:
+        with self._lock:
+            snapshots = [job.as_dict() for job in self._jobs.values()]
+            self._jobs.clear()
+        return snapshots
+
+    def list(self) -> list[dict[str, Any]]:
+        with self._lock:
+            return [job.as_dict() for job in self._jobs.values()]
+
+    def shutdown(self, timeout: float = 5.0) -> None:
+        self._stop.set()
+        thread = self._thread
+        self._thread = None
+        if thread is not None and thread.is_alive():
+            thread.join(timeout=timeout)
+
+    def __contains__(self, name: object) -> bool:
+        return isinstance(name, str) and name in self._jobs
+
+
+def _safe_execute(job_name: str, action_list: list[list[Any]]) -> None:
+    from automation_file.core.action_executor import executor
+
+    try:
+        executor.execute_action(action_list)
+    except FileAutomationException as error:
+        file_automation_logger.warning("scheduler[%s]: dispatch failed: %r", job_name, error)
+
+
+scheduler: Scheduler = Scheduler()
+
+
+def schedule_add(name: str, cron_expression: str, action_list: list[list[Any]]) -> dict[str, Any]:
+    """Register a named job that fires ``action_list`` on ``cron_expression``."""
+    return scheduler.add(name, cron_expression, action_list)
+
+
+def schedule_remove(name: str) -> dict[str, Any]:
+    """Remove the named job."""
+    return scheduler.remove(name)
+
+
+def schedule_remove_all() -> list[dict[str, Any]]:
+    """Remove every registered job and return their final snapshots."""
+    return scheduler.remove_all()
+
+
+def schedule_list() -> list[dict[str, Any]]:
+    """Return a snapshot of every registered job."""
+    return scheduler.list()
+
+
+def register_scheduler_ops(registry: ActionRegistry) -> None:
+    """Wire ``FA_schedule_*`` actions into a registry."""
+    registry.register_many(
+        {
+            "FA_schedule_add": schedule_add,
+            "FA_schedule_remove": schedule_remove,
+            "FA_schedule_remove_all": schedule_remove_all,
+            "FA_schedule_list": schedule_list,
+        }
+    )
diff --git a/automation_file/ui/main_window.py b/automation_file/ui/main_window.py
index 1ca5507..f422b4a 100644
--- a/automation_file/ui/main_window.py
+++ b/automation_file/ui/main_window.py
@@ -12,6 +12,7 @@
     HomeTab,
     JSONEditorTab,
     LocalOpsTab,
+    SchedulerTab,
     ServerTab,
     TransferTab,
     TriggerTab,
@@ -43,6 +44,8 @@ def __init__(self) -> None:
         self._tabs.addTab(JSONEditorTab(self._log, self._pool), "JSON actions")
         self._trigger_tab = TriggerTab(self._log, self._pool)
         self._tabs.addTab(self._trigger_tab, "Triggers")
+        self._scheduler_tab = SchedulerTab(self._log, self._pool)
+        self._tabs.addTab(self._scheduler_tab, "Scheduler")
         self._server_tab = ServerTab(self._log, self._pool)
         self._tabs.addTab(self._server_tab, "Servers")
 
@@ -80,4 +83,5 @@ def _on_log_message(self, message: str) -> None:
     def closeEvent(self, event) -> None:  # noqa: N802  # pylint: disable=invalid-name — Qt override
         self._server_tab.closeEvent(event)
         self._trigger_tab.closeEvent(event)
+        self._scheduler_tab.closeEvent(event)
         super().closeEvent(event)
diff --git a/automation_file/ui/tabs/__init__.py b/automation_file/ui/tabs/__init__.py
index 2387d86..26fa7e7 100644
--- a/automation_file/ui/tabs/__init__.py
+++ b/automation_file/ui/tabs/__init__.py
@@ -10,6 +10,7 @@
 from automation_file.ui.tabs.json_editor_tab import JSONEditorTab
 from automation_file.ui.tabs.local_tab import LocalOpsTab
 from automation_file.ui.tabs.s3_tab import S3Tab
+from automation_file.ui.tabs.scheduler_tab import SchedulerTab
 from automation_file.ui.tabs.server_tab import ServerTab
 from automation_file.ui.tabs.sftp_tab import SFTPTab
 from automation_file.ui.tabs.transfer_tab import TransferTab
@@ -25,6 +26,7 @@
     "LocalOpsTab",
     "S3Tab",
     "SFTPTab",
+    "SchedulerTab",
     "ServerTab",
     "TransferTab",
     "TriggerTab",
diff --git a/automation_file/ui/tabs/scheduler_tab.py b/automation_file/ui/tabs/scheduler_tab.py
new file mode 100644
index 0000000..26e5f78
--- /dev/null
+++ b/automation_file/ui/tabs/scheduler_tab.py
@@ -0,0 +1,155 @@
+"""Cron scheduler management tab.
+
+Lists active scheduled jobs, adds a new job from a cron expression plus an
+inline JSON action list, and removes jobs individually or in bulk. All
+dispatch goes through the shared :class:`ActionExecutor`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from PySide6.QtWidgets import (
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QHeaderView,
+    QLineEdit,
+    QPlainTextEdit,
+    QTableWidget,
+    QTableWidgetItem,
+    QVBoxLayout,
+)
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.scheduler import (
+    schedule_add,
+    schedule_list,
+    schedule_remove,
+    schedule_remove_all,
+)
+from automation_file.ui.tabs.base import BaseTab
+
+_COLUMNS = ("Name", "Cron", "Actions", "Runs", "Last run")
+
+
+class SchedulerTab(BaseTab):
+    """Add / remove / list cron-scheduled jobs."""
+
+    def __init__(self, log, pool) -> None:
+        super().__init__(log, pool)
+        root = QVBoxLayout(self)
+        root.setContentsMargins(12, 12, 12, 12)
+        root.setSpacing(12)
+        root.addWidget(self._add_group())
+        root.addWidget(self._list_group(), 1)
+        self._refresh()
+
+    def _add_group(self) -> QGroupBox:
+        box = QGroupBox("Schedule a job")
+        form = QFormLayout(box)
+        form.setVerticalSpacing(10)
+        form.setHorizontalSpacing(12)
+
+        self._name = QLineEdit()
+        self._name.setPlaceholderText("unique job name")
+        self._cron = QLineEdit("*/5 * * * *")
+        self._cron.setPlaceholderText("minute hour dom month dow  (e.g. */5 * * * *)")
+        self._actions = QPlainTextEdit()
+        self._actions.setPlaceholderText(
+            '[["FA_create_file", {"file_path": "scheduled.txt", "content": "tick"}]]'
+        )
+        self._actions.setMinimumHeight(120)
+
+        form.addRow("Name", self._name)
+        form.addRow("Cron", self._cron)
+        form.addRow("Actions (JSON)", self._actions)
+        form.addRow(self.make_button("Add job", self._on_add))
+        return box
+
+    def _list_group(self) -> QGroupBox:
+        box = QGroupBox("Active jobs")
+        layout = QVBoxLayout(box)
+        layout.setSpacing(8)
+
+        self._table = QTableWidget(0, len(_COLUMNS))
+        self._table.setHorizontalHeaderLabels(_COLUMNS)
+        header = self._table.horizontalHeader()
+        header.setSectionResizeMode(QHeaderView.ResizeMode.Stretch)
+        self._table.verticalHeader().setVisible(False)
+        self._table.setSelectionBehavior(QTableWidget.SelectionBehavior.SelectRows)
+        self._table.setEditTriggers(QTableWidget.EditTrigger.NoEditTriggers)
+        layout.addWidget(self._table)
+
+        row = QHBoxLayout()
+        row.setSpacing(8)
+        row.addWidget(self.make_button("Refresh", self._refresh))
+        row.addWidget(self.make_button("Remove selected", self._on_remove_selected))
+        row.addWidget(self.make_button("Remove all", self._on_remove_all))
+        row.addStretch()
+        layout.addLayout(row)
+        return box
+
+    def _on_add(self) -> None:
+        name = self._name.text().strip()
+        cron = self._cron.text().strip()
+        raw_actions = self._actions.toPlainText().strip()
+        if not name or not cron or not raw_actions:
+            self._log.append_line("scheduler: name, cron, and actions are all required")
+            return
+        try:
+            action_list = json.loads(raw_actions)
+        except json.JSONDecodeError as error:
+            self._log.append_line(f"scheduler: invalid JSON: {error}")
+            return
+        if not isinstance(action_list, list):
+            self._log.append_line("scheduler: action JSON must be an array")
+            return
+        try:
+            snapshot = schedule_add(name, cron, action_list)
+        except FileAutomationException as error:
+            self._log.append_line(f"scheduler: add failed: {error!r}")
+            return
+        self._log.append_line(f"scheduler: added {snapshot}")
+        self._refresh()
+
+    def _on_remove_selected(self) -> None:
+        row = self._table.currentRow()
+        if row < 0:
+            self._log.append_line("scheduler: no row selected")
+            return
+        name_item = self._table.item(row, 0)
+        if name_item is None:
+            return
+        name = name_item.text()
+        try:
+            snapshot = schedule_remove(name)
+        except FileAutomationException as error:
+            self._log.append_line(f"scheduler: remove failed: {error!r}")
+            return
+        self._log.append_line(f"scheduler: removed {snapshot}")
+        self._refresh()
+
+    def _on_remove_all(self) -> None:
+        snapshots = schedule_remove_all()
+        self._log.append_line(f"scheduler: removed {len(snapshots)} job(s)")
+        self._refresh()
+
+    def _refresh(self) -> None:
+        jobs = schedule_list()
+        self._table.setRowCount(len(jobs))
+        for row, data in enumerate(jobs):
+            self._set_cell(row, 0, data["name"])
+            self._set_cell(row, 1, data["cron"])
+            self._set_cell(row, 2, str(data["actions"]))
+            self._set_cell(row, 3, str(data["runs"]))
+            self._set_cell(row, 4, data["last_run"] or "—")
+
+    def _set_cell(self, row: int, col: int, text: str) -> None:
+        item = QTableWidgetItem(text)
+        self._table.setItem(row, col, item)
+
+    def closeEvent(self, event: Any) -> None:  # noqa: N802  # pylint: disable=invalid-name — Qt override
+        schedule_remove_all()
+        super().closeEvent(event)
diff --git a/tests/test_scheduler.py b/tests/test_scheduler.py
new file mode 100644
index 0000000..8a26385
--- /dev/null
+++ b/tests/test_scheduler.py
@@ -0,0 +1,166 @@
+"""Tests for the cron parser and scheduler registry wiring.
+
+The scheduler's live tick thread is intentionally *not* exercised here — we
+verify parser correctness, job CRUD, duplicate rejection, and registry
+wiring. End-to-end minute-boundary firing is covered manually / in the GUI.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+
+import pytest
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.scheduler.cron import CronException, CronExpression
+from automation_file.scheduler.manager import (
+    Scheduler,
+    SchedulerException,
+    _safe_execute,
+    register_scheduler_ops,
+)
+
+
+def test_cron_parses_star() -> None:
+    expression = CronExpression.parse("* * * * *")
+    assert 0 in expression.minutes and 59 in expression.minutes
+    assert expression.matches(dt.datetime(2026, 4, 21, 12, 30))
+
+
+def test_cron_parses_exact_minute() -> None:
+    expression = CronExpression.parse("30 9 * * *")
+    assert expression.minutes == frozenset({30})
+    assert expression.hours == frozenset({9})
+    assert expression.matches(dt.datetime(2026, 4, 21, 9, 30))
+    assert not expression.matches(dt.datetime(2026, 4, 21, 9, 31))
+
+
+def test_cron_parses_step() -> None:
+    expression = CronExpression.parse("*/15 * * * *")
+    assert expression.minutes == frozenset({0, 15, 30, 45})
+
+
+def test_cron_parses_range_with_step() -> None:
+    expression = CronExpression.parse("0 9-17/2 * * *")
+    assert expression.hours == frozenset({9, 11, 13, 15, 17})
+
+
+def test_cron_parses_list() -> None:
+    expression = CronExpression.parse("0,15,30 * * * *")
+    assert expression.minutes == frozenset({0, 15, 30})
+
+
+def test_cron_parses_month_and_dow_aliases() -> None:
+    expression = CronExpression.parse("0 0 * JAN mon")
+    assert expression.months == frozenset({1})
+    assert expression.weekdays == frozenset({1})
+
+
+def test_cron_dow_seven_aliases_to_sunday() -> None:
+    expression = CronExpression.parse("0 0 * * 7")
+    assert expression.weekdays == frozenset({0})
+
+
+def test_cron_rejects_wrong_field_count() -> None:
+    with pytest.raises(CronException):
+        CronExpression.parse("* * * *")
+
+
+def test_cron_rejects_out_of_range() -> None:
+    with pytest.raises(CronException):
+        CronExpression.parse("60 * * * *")
+
+
+def test_cron_rejects_empty_expression() -> None:
+    with pytest.raises(CronException):
+        CronExpression.parse("")
+
+
+def test_cron_exception_inherits_from_file_automation() -> None:
+    assert issubclass(CronException, FileAutomationException)
+
+
+def test_scheduler_add_remove_lifecycle() -> None:
+    engine = Scheduler()
+    try:
+        snapshot = engine.add("job-a", "*/5 * * * *", [["FA_schedule_list"]])
+        assert snapshot["name"] == "job-a"
+        assert snapshot["cron"] == "*/5 * * * *"
+        assert snapshot["runs"] == 0
+        assert "job-a" in engine
+        assert len(engine.list()) == 1
+        removed = engine.remove("job-a")
+        assert removed["name"] == "job-a"
+        assert engine.list() == []
+    finally:
+        engine.shutdown()
+
+
+def test_scheduler_rejects_duplicate_names() -> None:
+    engine = Scheduler()
+    try:
+        engine.add("dup", "* * * * *", [["FA_schedule_list"]])
+        with pytest.raises(SchedulerException):
+            engine.add("dup", "* * * * *", [["FA_schedule_list"]])
+    finally:
+        engine.shutdown()
+
+
+def test_scheduler_remove_unknown_raises() -> None:
+    engine = Scheduler()
+    try:
+        with pytest.raises(SchedulerException):
+            engine.remove("nope")
+    finally:
+        engine.shutdown()
+
+
+def test_scheduler_remove_all_clears_everything() -> None:
+    engine = Scheduler()
+    try:
+        engine.add("a", "* * * * *", [["FA_schedule_list"]])
+        engine.add("b", "* * * * *", [["FA_schedule_list"]])
+        snapshots = engine.remove_all()
+        assert len(snapshots) == 2
+        assert engine.list() == []
+    finally:
+        engine.shutdown()
+
+
+def test_scheduler_rejects_bad_cron() -> None:
+    engine = Scheduler()
+    try:
+        with pytest.raises(CronException):
+            engine.add("bad", "not a cron", [["FA_schedule_list"]])
+    finally:
+        engine.shutdown()
+
+
+def test_scheduler_exception_inherits_from_file_automation() -> None:
+    assert issubclass(SchedulerException, FileAutomationException)
+
+
+def test_register_scheduler_ops_populates_registry() -> None:
+    from automation_file.core.action_registry import ActionRegistry
+
+    registry = ActionRegistry()
+    register_scheduler_ops(registry)
+    for name in (
+        "FA_schedule_add",
+        "FA_schedule_remove",
+        "FA_schedule_remove_all",
+        "FA_schedule_list",
+    ):
+        assert name in registry
+
+
+def test_default_registry_contains_scheduler_ops() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    registry = build_default_registry()
+    assert "FA_schedule_add" in registry
+    assert "FA_schedule_list" in registry
+
+
+def test_safe_execute_swallows_exceptions_cleanly() -> None:
+    _safe_execute("unit-test", [["FA_does_not_exist"]])
diff --git a/tests/test_ui_smoke.py b/tests/test_ui_smoke.py
index 776096e..e426c96 100644
--- a/tests/test_ui_smoke.py
+++ b/tests/test_ui_smoke.py
@@ -55,6 +55,7 @@ def test_main_window_constructs(qt_app) -> None:
         "ServerTab",
         "TransferTab",
         "TriggerTab",
+        "SchedulerTab",
         "HomeTab",
     ],
 )

From c499f8468ee13838d0073b747ed8e8537e4a69da Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 20:18:15 +0800
Subject: [PATCH 03/38] Add transfer progress + cancellation primitives with UI
 tab

New automation_file.core.progress module exposes CancellationToken,
ProgressReporter, and a module-level ProgressRegistry keyed by a user-chosen
name. download_file and the S3 upload / download ops accept an optional
progress_name kwarg that wires a reporter + token through the transfer loop,
so the GUI or a JSON action can poll status or cancel mid-flight.
FA_progress_list / FA_progress_cancel / FA_progress_clear are auto-registered
alongside the other FA_* actions. Progress tab in the main window drives the
same lifecycle from the GUI.
---
 automation_file/__init__.py               |  21 +++
 automation_file/core/action_registry.py   |   7 +
 automation_file/core/progress.py          | 161 ++++++++++++++++++++++
 automation_file/remote/http_download.py   |  30 +++-
 automation_file/remote/s3/download_ops.py |  44 +++++-
 automation_file/remote/s3/upload_ops.py   |  38 ++++-
 automation_file/ui/main_window.py         |   2 +
 automation_file/ui/tabs/__init__.py       |   2 +
 automation_file/ui/tabs/progress_tab.py   | 127 +++++++++++++++++
 tests/test_progress.py                    | 124 +++++++++++++++++
 tests/test_ui_smoke.py                    |   1 +
 11 files changed, 550 insertions(+), 7 deletions(-)
 create mode 100644 automation_file/core/progress.py
 create mode 100644 automation_file/ui/tabs/progress_tab.py
 create mode 100644 tests/test_progress.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 5099283..240dd13 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -22,6 +22,17 @@
 from automation_file.core.callback_executor import CallbackExecutor
 from automation_file.core.json_store import read_action_json, write_action_json
 from automation_file.core.package_loader import PackageLoader
+from automation_file.core.progress import (
+    CancellationToken,
+    CancelledException,
+    ProgressRegistry,
+    ProgressReporter,
+    progress_cancel,
+    progress_clear,
+    progress_list,
+    progress_registry,
+    register_progress_ops,
+)
 from automation_file.core.quota import Quota
 from automation_file.core.retry import retry_on_transient
 from automation_file.local.dir_ops import copy_dir, create_dir, remove_dir_tree, rename_dir
@@ -226,6 +237,16 @@ def __getattr__(name: str) -> Any:
     "schedule_remove",
     "schedule_remove_all",
     "scheduler",
+    # Progress / cancellation
+    "CancellationToken",
+    "CancelledException",
+    "ProgressRegistry",
+    "ProgressReporter",
+    "progress_cancel",
+    "progress_clear",
+    "progress_list",
+    "progress_registry",
+    "register_progress_ops",
     # UI (lazy-loaded)
     "launch_ui",
 ]
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index cbf9f7b..690ab85 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -153,6 +153,12 @@ def _register_scheduler_ops(registry: ActionRegistry) -> None:
     register_scheduler_ops(registry)
 
 
+def _register_progress_ops(registry: ActionRegistry) -> None:
+    from automation_file.core.progress import register_progress_ops
+
+    register_progress_ops(registry)
+
+
 def build_default_registry() -> ActionRegistry:
     """Return a registry pre-populated with every built-in ``FA_*`` action."""
     registry = ActionRegistry()
@@ -162,6 +168,7 @@ def build_default_registry() -> ActionRegistry:
     _register_cloud_backends(registry)
     _register_trigger_ops(registry)
     _register_scheduler_ops(registry)
+    _register_progress_ops(registry)
     file_automation_logger.info(
         "action_registry: built default registry with %d commands", len(registry)
     )
diff --git a/automation_file/core/progress.py b/automation_file/core/progress.py
new file mode 100644
index 0000000..92ea7c4
--- /dev/null
+++ b/automation_file/core/progress.py
@@ -0,0 +1,161 @@
+"""Transfer progress + cancellation primitives.
+
+Long-running transfers (HTTP downloads, S3 uploads/downloads, …) accept a
+named handle from the shared :data:`progress_registry`. The registry keeps a
+:class:`ProgressReporter` (bytes transferred, optional total) and a
+:class:`CancellationToken` per name so the GUI or a JSON action can observe
+progress or cancel mid-flight.
+
+Instrumentation is opt-in: callers pass ``progress_name="<label>"`` to enable
+tracking. When omitted, transfers run exactly as before with zero overhead
+beyond one attribute lookup.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from automation_file.exceptions import FileAutomationException
+
+
+class CancelledException(FileAutomationException):
+    """Raised when a cancellable operation is asked to stop mid-flight."""
+
+
+class CancellationToken:
+    """Thread-safe boolean flag, pollable from worker threads."""
+
+    def __init__(self) -> None:
+        self._event = threading.Event()
+
+    def cancel(self) -> None:
+        self._event.set()
+
+    @property
+    def is_cancelled(self) -> bool:
+        return self._event.is_set()
+
+    def raise_if_cancelled(self) -> None:
+        if self._event.is_set():
+            raise CancelledException("operation cancelled")
+
+
+@dataclass
+class ProgressReporter:
+    """Tracks bytes transferred for one named operation."""
+
+    name: str
+    total: int | None = None
+    transferred: int = 0
+    status: str = "running"
+    started_at: float = field(default_factory=time.monotonic)
+    finished_at: float | None = None
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def update(self, delta: int) -> None:
+        if delta <= 0:
+            return
+        with self._lock:
+            self.transferred += delta
+
+    def finish(self, status: str = "done") -> None:
+        with self._lock:
+            self.status = status
+            self.finished_at = time.monotonic()
+
+    @property
+    def is_finished(self) -> bool:
+        return self.finished_at is not None
+
+    def snapshot(self) -> dict[str, Any]:
+        with self._lock:
+            return {
+                "name": self.name,
+                "total": self.total,
+                "transferred": self.transferred,
+                "status": self.status,
+                "started_at": self.started_at,
+                "finished_at": self.finished_at,
+            }
+
+
+class ProgressRegistry:
+    """Named handles so JSON actions / the GUI can address ongoing transfers."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._entries: dict[str, tuple[ProgressReporter, CancellationToken]] = {}
+
+    def create(
+        self, name: str, total: int | None = None
+    ) -> tuple[ProgressReporter, CancellationToken]:
+        reporter = ProgressReporter(name=name, total=total)
+        token = CancellationToken()
+        with self._lock:
+            self._entries[name] = (reporter, token)
+        return reporter, token
+
+    def lookup(self, name: str) -> tuple[ProgressReporter, CancellationToken] | None:
+        with self._lock:
+            return self._entries.get(name)
+
+    def cancel(self, name: str) -> bool:
+        with self._lock:
+            entry = self._entries.get(name)
+        if entry is None:
+            return False
+        entry[1].cancel()
+        return True
+
+    def forget(self, name: str) -> bool:
+        with self._lock:
+            return self._entries.pop(name, None) is not None
+
+    def clear_finished(self) -> int:
+        with self._lock:
+            finished = [
+                name for name, (reporter, _) in self._entries.items() if reporter.is_finished
+            ]
+            for name in finished:
+                self._entries.pop(name, None)
+        return len(finished)
+
+    def list(self) -> list[dict[str, Any]]:
+        with self._lock:
+            snapshots = [reporter.snapshot() for reporter, _ in self._entries.values()]
+        return snapshots
+
+    def __contains__(self, name: object) -> bool:
+        return isinstance(name, str) and name in self._entries
+
+
+progress_registry: ProgressRegistry = ProgressRegistry()
+
+
+def progress_list() -> list[dict[str, Any]]:
+    """Snapshot of every registered transfer."""
+    return progress_registry.list()
+
+
+def progress_cancel(name: str) -> bool:
+    """Cancel the named transfer. Returns ``False`` if no such handle."""
+    return progress_registry.cancel(name)
+
+
+def progress_clear() -> int:
+    """Drop every finished transfer from the registry."""
+    return progress_registry.clear_finished()
+
+
+def register_progress_ops(registry: Any) -> None:
+    """Wire ``FA_progress_*`` actions into an :class:`ActionRegistry`."""
+    registry.register_many(
+        {
+            "FA_progress_list": progress_list,
+            "FA_progress_cancel": progress_cancel,
+            "FA_progress_clear": progress_clear,
+        }
+    )
diff --git a/automation_file/remote/http_download.py b/automation_file/remote/http_download.py
index 1b83382..7c09489 100644
--- a/automation_file/remote/http_download.py
+++ b/automation_file/remote/http_download.py
@@ -5,6 +5,11 @@
 import requests
 from tqdm import tqdm
 
+from automation_file.core.progress import (
+    CancelledException,
+    ProgressReporter,
+    progress_registry,
+)
 from automation_file.core.retry import retry_on_transient
 from automation_file.exceptions import RetryExhaustedException, UrlValidationException
 from automation_file.logging_config import file_automation_logger
@@ -42,12 +47,15 @@ def download_file(
     chunk_size: int = _DEFAULT_CHUNK_SIZE,
     timeout: int = _DEFAULT_TIMEOUT_SECONDS,
     max_bytes: int = _MAX_RESPONSE_BYTES,
+    progress_name: str | None = None,
 ) -> bool:
     """Download ``file_url`` to ``file_name`` with progress display.
 
     Validates the URL against SSRF rules, disables redirects, enforces a size
     cap, retries transient network errors up to three times, and uses default
-    TLS verification. Returns True on success.
+    TLS verification. Pass ``progress_name`` to register the transfer with
+    :data:`~automation_file.core.progress.progress_registry` so it can be
+    polled or cancelled from the GUI. Returns True on success.
     """
     try:
         validate_http_url(file_url)
@@ -76,10 +84,17 @@ def download_file(
         )
         return False
 
+    reporter: ProgressReporter | None = None
+    token = None
+    if progress_name:
+        reporter, token = progress_registry.create(progress_name, total=total_size or None)
+
     written = 0
     try:
         with open(file_name, "wb") as output, _progress(total_size, file_name) as progress:
             for chunk in response.iter_content(chunk_size=chunk_size):
+                if token is not None:
+                    token.raise_if_cancelled()
                 if not chunk:
                     continue
                 written += len(chunk)
@@ -88,13 +103,26 @@ def download_file(
                         "download_file aborted: stream exceeded %d bytes",
                         max_bytes,
                     )
+                    if reporter is not None:
+                        reporter.finish(status="aborted")
                     return False
                 output.write(chunk)
                 progress.update(len(chunk))
+                if reporter is not None:
+                    reporter.update(len(chunk))
+    except CancelledException:
+        file_automation_logger.warning("download_file cancelled: %s", progress_name)
+        if reporter is not None:
+            reporter.finish(status="cancelled")
+        return False
     except OSError as error:
         file_automation_logger.error("download_file write error: %r", error)
+        if reporter is not None:
+            reporter.finish(status="error")
         return False
 
+    if reporter is not None:
+        reporter.finish(status="done")
     file_automation_logger.info("download_file: %s -> %s (%d bytes)", file_url, file_name, written)
     return True
 
diff --git a/automation_file/remote/s3/download_ops.py b/automation_file/remote/s3/download_ops.py
index 3e6a85f..137590f 100644
--- a/automation_file/remote/s3/download_ops.py
+++ b/automation_file/remote/s3/download_ops.py
@@ -4,16 +4,47 @@
 
 from pathlib import Path
 
+from automation_file.core.progress import (
+    CancelledException,
+    progress_registry,
+)
 from automation_file.logging_config import file_automation_logger
 from automation_file.remote.s3.client import s3_instance
 
 
-def s3_download_file(bucket: str, key: str, target_path: str) -> bool:
-    """Download ``s3://bucket/key`` to ``target_path``."""
+def s3_download_file(
+    bucket: str,
+    key: str,
+    target_path: str,
+    progress_name: str | None = None,
+) -> bool:
+    """Download ``s3://bucket/key`` to ``target_path``.
+
+    Pass ``progress_name`` to register the transfer with the shared progress
+    registry so it can be polled or cancelled mid-flight.
+    """
     client = s3_instance.require_client()
     Path(target_path).parent.mkdir(parents=True, exist_ok=True)
+    callback = None
+    reporter = None
+    token = None
+    if progress_name:
+        total = None
+        try:
+            head = client.head_object(Bucket=bucket, Key=key)
+            total = int(head.get("ContentLength", 0)) or None
+        except Exception:  # pylint: disable=broad-except
+            total = None
+        reporter, token = progress_registry.create(progress_name, total=total)
+
+        def callback(bytes_transferred: int) -> None:
+            token.raise_if_cancelled()
+            reporter.update(bytes_transferred)
+
     try:
-        client.download_file(bucket, key, target_path)
+        client.download_file(bucket, key, target_path, Callback=callback)
+        if reporter is not None:
+            reporter.finish(status="done")
         file_automation_logger.info(
             "s3_download_file: s3://%s/%s -> %s",
             bucket,
@@ -21,6 +52,13 @@ def s3_download_file(bucket: str, key: str, target_path: str) -> bool:
             target_path,
         )
         return True
+    except CancelledException:
+        file_automation_logger.warning("s3_download_file cancelled: %s", progress_name)
+        if reporter is not None:
+            reporter.finish(status="cancelled")
+        return False
     except Exception as error:  # pylint: disable=broad-except
+        if reporter is not None:
+            reporter.finish(status="error")
         file_automation_logger.error("s3_download_file failed: %r", error)
         return False
diff --git a/automation_file/remote/s3/upload_ops.py b/automation_file/remote/s3/upload_ops.py
index 27e1030..dadd85b 100644
--- a/automation_file/remote/s3/upload_ops.py
+++ b/automation_file/remote/s3/upload_ops.py
@@ -4,23 +4,55 @@
 
 from pathlib import Path
 
+from automation_file.core.progress import (
+    CancelledException,
+    progress_registry,
+)
 from automation_file.exceptions import FileNotExistsException
 from automation_file.logging_config import file_automation_logger
 from automation_file.remote._upload_tree import walk_and_upload
 from automation_file.remote.s3.client import s3_instance
 
 
-def s3_upload_file(file_path: str, bucket: str, key: str) -> bool:
-    """Upload a single file to ``s3://bucket/key``."""
+def s3_upload_file(
+    file_path: str,
+    bucket: str,
+    key: str,
+    progress_name: str | None = None,
+) -> bool:
+    """Upload a single file to ``s3://bucket/key``.
+
+    Pass ``progress_name`` to register the transfer with the shared progress
+    registry so it can be polled or cancelled mid-flight.
+    """
     path = Path(file_path)
     if not path.is_file():
         raise FileNotExistsException(str(path))
     client = s3_instance.require_client()
+    callback = None
+    reporter = None
+    token = None
+    if progress_name:
+        reporter, token = progress_registry.create(progress_name, total=path.stat().st_size)
+
+        def callback(bytes_transferred: int) -> None:
+            token.raise_if_cancelled()
+            reporter.update(bytes_transferred)
+
     try:
-        client.upload_file(str(path), bucket, key)
+        client.upload_file(str(path), bucket, key, Callback=callback)
+        if reporter is not None:
+            reporter.finish(status="done")
         file_automation_logger.info("s3_upload_file: %s -> s3://%s/%s", path, bucket, key)
         return True
+    except CancelledException:
+        file_automation_logger.warning("s3_upload_file cancelled: %s", progress_name)
+        if reporter is not None:
+            reporter.finish(status="cancelled")
+        return False
     except Exception as error:  # pylint: disable=broad-except
+        if reporter is not None:
+            reporter.finish(status="error")
         file_automation_logger.error("s3_upload_file failed: %r", error)
         return False
 
diff --git a/automation_file/ui/main_window.py b/automation_file/ui/main_window.py
index f422b4a..3e1e3e9 100644
--- a/automation_file/ui/main_window.py
+++ b/automation_file/ui/main_window.py
@@ -12,6 +12,7 @@
     HomeTab,
     JSONEditorTab,
     LocalOpsTab,
+    ProgressTab,
     SchedulerTab,
     ServerTab,
     TransferTab,
@@ -41,6 +42,7 @@ def __init__(self) -> None:
         self._tabs.addTab(self._home_tab, "Home")
         self._tabs.addTab(LocalOpsTab(self._log, self._pool), "Local")
         self._tabs.addTab(TransferTab(self._log, self._pool), "Transfer")
+        self._tabs.addTab(ProgressTab(self._log, self._pool), "Progress")
         self._tabs.addTab(JSONEditorTab(self._log, self._pool), "JSON actions")
         self._trigger_tab = TriggerTab(self._log, self._pool)
         self._tabs.addTab(self._trigger_tab, "Triggers")
diff --git a/automation_file/ui/tabs/__init__.py b/automation_file/ui/tabs/__init__.py
index 26fa7e7..8142f19 100644
--- a/automation_file/ui/tabs/__init__.py
+++ b/automation_file/ui/tabs/__init__.py
@@ -9,6 +9,7 @@
 from automation_file.ui.tabs.http_tab import HTTPDownloadTab
 from automation_file.ui.tabs.json_editor_tab import JSONEditorTab
 from automation_file.ui.tabs.local_tab import LocalOpsTab
+from automation_file.ui.tabs.progress_tab import ProgressTab
 from automation_file.ui.tabs.s3_tab import S3Tab
 from automation_file.ui.tabs.scheduler_tab import SchedulerTab
 from automation_file.ui.tabs.server_tab import ServerTab
@@ -24,6 +25,7 @@
     "HomeTab",
     "JSONEditorTab",
     "LocalOpsTab",
+    "ProgressTab",
     "S3Tab",
     "SFTPTab",
     "SchedulerTab",
diff --git a/automation_file/ui/tabs/progress_tab.py b/automation_file/ui/tabs/progress_tab.py
new file mode 100644
index 0000000..2515388
--- /dev/null
+++ b/automation_file/ui/tabs/progress_tab.py
@@ -0,0 +1,127 @@
+"""Transfer progress + cancel management tab.
+
+Polls :data:`~automation_file.core.progress.progress_registry` on a timer and
+renders one row per active / finished transfer. Users can cancel a running
+transfer or clear completed rows.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from PySide6.QtCore import QThreadPool, QTimer
+from PySide6.QtWidgets import (
+    QGroupBox,
+    QHBoxLayout,
+    QHeaderView,
+    QProgressBar,
+    QTableWidget,
+    QTableWidgetItem,
+    QVBoxLayout,
+)
+
+from automation_file.core.progress import (
+    progress_clear,
+    progress_list,
+    progress_registry,
+)
+from automation_file.ui.log_widget import LogPanel
+from automation_file.ui.tabs.base import BaseTab
+
+_REFRESH_INTERVAL_MS = 500
+_COLUMNS = ("Name", "Status", "Progress", "Transferred", "Total")
+
+
+class ProgressTab(BaseTab):
+    """Live view of every registered transfer."""
+
+    def __init__(self, log: LogPanel, pool: QThreadPool) -> None:
+        super().__init__(log, pool)
+        root = QVBoxLayout(self)
+        root.setContentsMargins(12, 12, 12, 12)
+        root.setSpacing(12)
+        root.addWidget(self._table_group(), 1)
+
+        self._timer = QTimer(self)
+        self._timer.setInterval(_REFRESH_INTERVAL_MS)
+        self._timer.timeout.connect(self._refresh)
+        self._timer.start()
+        self._refresh()
+
+    def _table_group(self) -> QGroupBox:
+        box = QGroupBox("Transfers")
+        layout = QVBoxLayout(box)
+        layout.setSpacing(8)
+
+        self._table = QTableWidget(0, len(_COLUMNS))
+        self._table.setHorizontalHeaderLabels(_COLUMNS)
+        header = self._table.horizontalHeader()
+        header.setSectionResizeMode(QHeaderView.ResizeMode.Stretch)
+        self._table.verticalHeader().setVisible(False)
+        self._table.setSelectionBehavior(QTableWidget.SelectionBehavior.SelectRows)
+        self._table.setEditTriggers(QTableWidget.EditTrigger.NoEditTriggers)
+        layout.addWidget(self._table)
+
+        row = QHBoxLayout()
+        row.setSpacing(8)
+        row.addWidget(self.make_button("Refresh", self._refresh))
+        row.addWidget(self.make_button("Cancel selected", self._on_cancel_selected))
+        row.addWidget(self.make_button("Clear finished", self._on_clear_finished))
+        row.addStretch()
+        layout.addLayout(row)
+        return box
+
+    def _on_cancel_selected(self) -> None:
+        row = self._table.currentRow()
+        if row < 0:
+            self._log.append_line("progress: no row selected")
+            return
+        name_item = self._table.item(row, 0)
+        if name_item is None:
+            return
+        name = name_item.text()
+        if progress_registry.cancel(name):
+            self._log.append_line(f"progress: cancel requested for {name!r}")
+        else:
+            self._log.append_line(f"progress: no such transfer: {name!r}")
+
+    def _on_clear_finished(self) -> None:
+        dropped = progress_clear()
+        self._log.append_line(f"progress: cleared {dropped} finished transfer(s)")
+        self._refresh()
+
+    def _refresh(self) -> None:
+        snapshots = progress_list()
+        self._table.setRowCount(len(snapshots))
+        for row, data in enumerate(snapshots):
+            self._set_cell(row, 0, data["name"])
+            self._set_cell(row, 1, data["status"])
+            self._table.setCellWidget(row, 2, self._progress_widget(data))
+            self._set_cell(row, 3, _format_bytes(data["transferred"]))
+            total = data["total"]
+            self._set_cell(row, 4, _format_bytes(total) if total else "unknown")
+
+    def _progress_widget(self, data: dict[str, Any]) -> QProgressBar:
+        bar = QProgressBar()
+        total = data["total"]
+        transferred = data["transferred"]
+        if total and total > 0:
+            bar.setRange(0, int(total))
+            bar.setValue(min(int(transferred), int(total)))
+        else:
+            bar.setRange(0, 0)  # busy indicator
+        return bar
+
+    def _set_cell(self, row: int, col: int, text: str) -> None:
+        self._table.setItem(row, col, QTableWidgetItem(text))
+
+
+def _format_bytes(value: int | None) -> str:
+    if value is None:
+        return "—"
+    size = float(value)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if size < 1024.0:
+            return f"{size:.1f} {unit}" if unit != "B" else f"{int(size)} {unit}"
+        size /= 1024.0
+    return f"{size:.1f} PB"
diff --git a/tests/test_progress.py b/tests/test_progress.py
new file mode 100644
index 0000000..ec89a5d
--- /dev/null
+++ b/tests/test_progress.py
@@ -0,0 +1,124 @@
+"""Tests for transfer progress + cancellation primitives."""
+
+from __future__ import annotations
+
+import threading
+
+import pytest
+
+from automation_file.core.progress import (
+    CancellationToken,
+    CancelledException,
+    ProgressRegistry,
+    ProgressReporter,
+    register_progress_ops,
+)
+from automation_file.exceptions import FileAutomationException
+
+
+def test_cancellation_token_flag_roundtrip() -> None:
+    token = CancellationToken()
+    assert not token.is_cancelled
+    token.cancel()
+    assert token.is_cancelled
+
+
+def test_cancellation_token_raise_if_cancelled() -> None:
+    token = CancellationToken()
+    token.raise_if_cancelled()  # no-op
+    token.cancel()
+    with pytest.raises(CancelledException):
+        token.raise_if_cancelled()
+
+
+def test_cancelled_exception_inherits_from_file_automation() -> None:
+    assert issubclass(CancelledException, FileAutomationException)
+
+
+def test_progress_reporter_tracks_bytes_and_status() -> None:
+    reporter = ProgressReporter(name="test", total=100)
+    reporter.update(30)
+    reporter.update(0)
+    reporter.update(-5)
+    reporter.update(20)
+    snapshot = reporter.snapshot()
+    assert snapshot["transferred"] == 50
+    assert snapshot["status"] == "running"
+    assert not reporter.is_finished
+    reporter.finish(status="done")
+    assert reporter.is_finished
+    assert reporter.snapshot()["status"] == "done"
+
+
+def test_progress_reporter_thread_safety() -> None:
+    reporter = ProgressReporter(name="race", total=10_000)
+
+    def worker() -> None:
+        for _ in range(1000):
+            reporter.update(1)
+
+    threads = [threading.Thread(target=worker) for _ in range(10)]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join()
+    assert reporter.snapshot()["transferred"] == 10_000
+
+
+def test_progress_registry_create_lookup_cancel() -> None:
+    registry = ProgressRegistry()
+    reporter, token = registry.create("job-1", total=500)
+    assert "job-1" in registry
+    fetched = registry.lookup("job-1")
+    assert fetched is not None
+    assert fetched[0] is reporter
+    assert fetched[1] is token
+    assert registry.cancel("job-1") is True
+    assert token.is_cancelled
+    assert registry.cancel("missing") is False
+
+
+def test_progress_registry_list_returns_snapshots() -> None:
+    registry = ProgressRegistry()
+    registry.create("a", total=100)
+    registry.create("b")
+    listing = registry.list()
+    assert {entry["name"] for entry in listing} == {"a", "b"}
+    assert all(entry["status"] == "running" for entry in listing)
+
+
+def test_progress_registry_clear_finished() -> None:
+    registry = ProgressRegistry()
+    reporter_a, _ = registry.create("done")
+    registry.create("still-running")
+    reporter_a.finish(status="done")
+    dropped = registry.clear_finished()
+    assert dropped == 1
+    names = [entry["name"] for entry in registry.list()]
+    assert names == ["still-running"]
+
+
+def test_progress_registry_forget() -> None:
+    registry = ProgressRegistry()
+    registry.create("forget-me")
+    assert registry.forget("forget-me") is True
+    assert "forget-me" not in registry
+    assert registry.forget("never-there") is False
+
+
+def test_register_progress_ops_populates_registry() -> None:
+    from automation_file.core.action_registry import ActionRegistry
+
+    action_registry = ActionRegistry()
+    register_progress_ops(action_registry)
+    for name in ("FA_progress_list", "FA_progress_cancel", "FA_progress_clear"):
+        assert name in action_registry
+
+
+def test_default_registry_contains_progress_ops() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    registry = build_default_registry()
+    assert "FA_progress_list" in registry
+    assert "FA_progress_cancel" in registry
+    assert "FA_progress_clear" in registry
diff --git a/tests/test_ui_smoke.py b/tests/test_ui_smoke.py
index e426c96..4befaf1 100644
--- a/tests/test_ui_smoke.py
+++ b/tests/test_ui_smoke.py
@@ -56,6 +56,7 @@ def test_main_window_constructs(qt_app) -> None:
         "TransferTab",
         "TriggerTab",
         "SchedulerTab",
+        "ProgressTab",
         "HomeTab",
     ],
 )

From e1ddf3b7241ee237501e239eda21d7ee7af98bdd Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 20:23:01 +0800
Subject: [PATCH 04/38] Document triggers, scheduler, and progress features

---
 README.md                     | 80 +++++++++++++++++++++++++++++++++--
 docs/source/api/index.rst     |  3 ++
 docs/source/api/progress.rst  | 12 ++++++
 docs/source/api/scheduler.rst | 17 ++++++++
 docs/source/api/trigger.rst   | 13 ++++++
 docs/source/api/ui.rst        |  9 ++++
 docs/source/architecture.rst  | 35 ++++++++++++++-
 docs/source/usage.rst         | 76 ++++++++++++++++++++++++++++++++-
 8 files changed, 239 insertions(+), 6 deletions(-)
 create mode 100644 docs/source/api/progress.rst
 create mode 100644 docs/source/api/scheduler.rst
 create mode 100644 docs/source/api/trigger.rst

diff --git a/README.md b/README.md
index e781ad8..310f636 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,10 @@ facade.
 - JSON action lists executed by a shared `ActionExecutor` — validate, dry-run, parallel
 - Loopback-first TCP **and** HTTP servers that accept JSON command batches with optional shared-secret auth
 - Reliability primitives: `retry_on_transient` decorator, `Quota` size / time budgets
-- PySide6 GUI (`python -m automation_file ui`) with a tab per backend plus a JSON-action runner
+- **File-watcher triggers** — run an action list whenever a path changes (`FA_watch_*`)
+- **Cron scheduler** — recurring action lists on a stdlib-only 5-field parser (`FA_schedule_*`)
+- **Transfer progress + cancellation** — opt-in `progress_name` hook on HTTP and S3 transfers (`FA_progress_*`)
+- PySide6 GUI (`python -m automation_file ui`) with a tab per backend, the JSON-action runner, and dedicated tabs for Triggers, Scheduler, and live Progress
 - Rich CLI with one-shot subcommands plus legacy JSON-batch flags
 - Project scaffolding (`ProjectBuilder`) for executor-based automations
 
@@ -36,6 +39,12 @@ flowchart LR
         Json[json_store]
         Retry[retry]
         QuotaMod[quota]
+        Progress[progress<br/>Token + Reporter]
+    end
+
+    subgraph Events["event-driven"]
+        TriggerMod["trigger<br/>watchdog file watcher"]
+        SchedulerMod["scheduler<br/>cron background thread"]
     end
 
     subgraph Local["local"]
@@ -101,6 +110,14 @@ flowchart LR
     Registry --> Dropbox
     Registry --> SFTP
     Registry --> Builder
+    Registry --> TriggerMod
+    Registry --> SchedulerMod
+    Registry --> Progress
+
+    TriggerMod --> Executor
+    SchedulerMod --> Executor
+    Http --> Progress
+    S3 --> Progress
 
     Http --> UrlVal
     Http --> Retry
@@ -130,7 +147,7 @@ Requirements:
 - Python 3.10+
 - Bundled dependencies: `google-api-python-client`, `google-auth-oauthlib`,
   `requests`, `tqdm`, `boto3`, `azure-storage-blob`, `dropbox`, `paramiko`,
-  `PySide6`
+  `PySide6`, `watchdog`
 
 ## Usage
 
@@ -240,6 +257,63 @@ All backends (`s3`, `azure_blob`, `dropbox_api`, `sftp`) expose the same five
 operations: `upload_file`, `upload_dir`, `download_file`, `delete_*`, `list_*`.
 SFTP uses `paramiko.RejectPolicy` — unknown hosts are rejected, not auto-added.
 
+### File-watcher triggers
+Run an action list whenever a filesystem event fires on a watched path:
+
+```python
+from automation_file import watch_start, watch_stop
+
+watch_start(
+    name="inbox-sweeper",
+    path="/data/inbox",
+    action_list=[["FA_copy_all_file_to_dir", {"source_dir": "/data/inbox",
+                                              "target_dir": "/data/processed"}]],
+    events=["created", "modified"],
+    recursive=False,
+)
+# later:
+watch_stop("inbox-sweeper")
+```
+
+`FA_watch_start` / `FA_watch_stop` / `FA_watch_stop_all` / `FA_watch_list`
+surface the same lifecycle to JSON action lists.
+
+### Cron scheduler
+Recurring action lists on a stdlib-only 5-field cron parser:
+
+```python
+from automation_file import schedule_add
+
+schedule_add(
+    name="nightly-snapshot",
+    cron_expression="0 2 * * *",        # every day at 02:00 local time
+    action_list=[["FA_zip_dir", {"dir_we_want_to_zip": "/data",
+                                 "zip_name": "/backup/data_nightly"}]],
+)
+```
+
+Supports `*`, exact values, `a-b` ranges, comma lists, and `*/n` step
+syntax with `jan..dec` / `sun..sat` aliases. JSON actions:
+`FA_schedule_add`, `FA_schedule_remove`, `FA_schedule_remove_all`,
+`FA_schedule_list`.
+
+### Transfer progress + cancellation
+HTTP and S3 transfers accept an opt-in `progress_name` kwarg:
+
+```python
+from automation_file import download_file, progress_cancel
+
+download_file("https://example.com/big.bin", "big.bin",
+              progress_name="big-download")
+
+# From another thread or the GUI:
+progress_cancel("big-download")
+```
+
+The shared `progress_registry` exposes live snapshots via `progress_list()`
+and the `FA_progress_list` / `FA_progress_cancel` / `FA_progress_clear` JSON
+actions. The GUI's **Progress** tab polls the registry every half second.
+
 ### GUI
 ```bash
 python -m automation_file ui        # or: python main_ui.py
@@ -250,7 +324,7 @@ from automation_file import launch_ui
 launch_ui()
 ```
 
-Tabs: Local, HTTP, Google Drive, S3, Azure Blob, Dropbox, SFTP, JSON actions,
+Tabs: Home, Local, Transfer, Progress, JSON actions, Triggers, Scheduler,
 Servers. A persistent log panel at the bottom streams every result and error.
 
 ### Scaffold an executor-based project
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index 4836f89..16c916d 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -8,6 +8,9 @@ API reference
    local
    remote
    server
+   trigger
+   scheduler
+   progress
    project
    ui
    utils
diff --git a/docs/source/api/progress.rst b/docs/source/api/progress.rst
new file mode 100644
index 0000000..237bf18
--- /dev/null
+++ b/docs/source/api/progress.rst
@@ -0,0 +1,12 @@
+Progress + cancellation
+=======================
+
+Opt-in transfer instrumentation. Pass ``progress_name="<label>"`` to
+:func:`~automation_file.download_file`, :func:`s3_upload_file`, or
+:func:`s3_download_file` and the transfer registers with the shared
+:data:`~automation_file.core.progress.progress_registry`. From there the GUI
+or a JSON action can poll the reporter snapshot or cancel the transfer
+mid-flight.
+
+.. automodule:: automation_file.core.progress
+   :members:
diff --git a/docs/source/api/scheduler.rst b/docs/source/api/scheduler.rst
new file mode 100644
index 0000000..31cffb7
--- /dev/null
+++ b/docs/source/api/scheduler.rst
@@ -0,0 +1,17 @@
+Scheduler
+=========
+
+Cron-style scheduler for recurring action lists. The parser understands the
+standard 5-field syntax (minute hour day-of-month month day-of-week) with
+``*``, ranges, lists, and ``*/n`` steps plus month / day-of-week aliases. A
+background thread wakes on minute boundaries and dispatches every matching
+job through the shared :class:`ActionExecutor`.
+
+.. automodule:: automation_file.scheduler
+   :members:
+
+.. automodule:: automation_file.scheduler.cron
+   :members:
+
+.. automodule:: automation_file.scheduler.manager
+   :members:
diff --git a/docs/source/api/trigger.rst b/docs/source/api/trigger.rst
new file mode 100644
index 0000000..872b158
--- /dev/null
+++ b/docs/source/api/trigger.rst
@@ -0,0 +1,13 @@
+Triggers
+========
+
+Watch local paths with ``watchdog`` and dispatch an action list whenever a
+matching filesystem event fires. The module-level
+:data:`~automation_file.trigger.trigger_manager` keeps a named registry of
+active watchers so the JSON facade and the GUI share one lifecycle.
+
+.. automodule:: automation_file.trigger
+   :members:
+
+.. automodule:: automation_file.trigger.manager
+   :members:
diff --git a/docs/source/api/ui.rst b/docs/source/api/ui.rst
index 29ec5d1..f61e181 100644
--- a/docs/source/api/ui.rst
+++ b/docs/source/api/ui.rst
@@ -70,3 +70,12 @@ Tabs
 
 .. automodule:: automation_file.ui.tabs.server_tab
    :members:
+
+.. automodule:: automation_file.ui.tabs.trigger_tab
+   :members:
+
+.. automodule:: automation_file.ui.tabs.scheduler_tab
+   :members:
+
+.. automodule:: automation_file.ui.tabs.progress_tab
+   :members:
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
index 3a488b5..1ea85d3 100644
--- a/docs/source/architecture.rst
+++ b/docs/source/architecture.rst
@@ -52,7 +52,8 @@ Module layout
    │   ├── package_loader.py
    │   ├── json_store.py
    │   ├── retry.py             # @retry_on_transient
-   │   └── quota.py             # Quota(max_bytes, max_seconds)
+   │   ├── quota.py             # Quota(max_bytes, max_seconds)
+   │   └── progress.py          # CancellationToken, ProgressReporter, progress_registry
    ├── local/
    │   ├── file_ops.py
    │   ├── dir_ops.py
@@ -69,12 +70,19 @@ Module layout
    ├── server/
    │   ├── tcp_server.py        # loopback-only, optional shared-secret
    │   └── http_server.py       # POST /actions, Bearer auth
+   ├── trigger/
+   │   └── manager.py           # FileWatcher + TriggerManager (watchdog-backed)
+   ├── scheduler/
+   │   ├── cron.py              # 5-field cron expression parser
+   │   └── manager.py           # Scheduler background thread + ScheduledJob
    ├── project/
    │   ├── project_builder.py
    │   └── templates.py
    ├── ui/                      # PySide6 GUI
    │   ├── launcher.py          # launch_ui(argv)
-   │   ├── main_window.py       # 9-tab MainWindow
+   │   ├── main_window.py       # tabbed MainWindow (Home, Local, Transfer,
+   │   │                        #   Progress, JSON actions, Triggers,
+   │   │                        #   Scheduler, Servers)
    │   ├── worker.py            # ActionWorker (QRunnable)
    │   ├── log_widget.py        # LogPanel
    │   └── tabs/                # one tab per backend + JSON runner + servers
@@ -105,6 +113,29 @@ Reliability utilities
   exponential back-off. Used by :func:`automation_file.download_file`.
 * :class:`automation_file.core.quota.Quota` — dataclass bundling an optional
   ``max_bytes`` size cap and an optional ``max_seconds`` time budget.
+* :class:`automation_file.core.progress.CancellationToken` and
+  :class:`automation_file.core.progress.ProgressReporter` — opt-in per-transfer
+  instrumentation. HTTP download and S3 upload/download accept a
+  ``progress_name=`` kwarg that wires both primitives into the transfer loop;
+  JSON actions ``FA_progress_list`` / ``FA_progress_cancel`` /
+  ``FA_progress_clear`` address the central registry.
+
+Event-driven dispatch
+---------------------
+
+Two long-running subsystems reuse the shared executor instead of forking
+their own dispatch paths:
+
+* :mod:`automation_file.trigger` wraps ``watchdog`` observers. Each
+  :class:`~automation_file.trigger.FileWatcher` forwards matching filesystem
+  events to an action list dispatched through the shared registry.
+  :data:`~automation_file.trigger.trigger_manager` owns the name → watcher
+  map so the GUI and JSON actions share one lifecycle.
+* :mod:`automation_file.scheduler` runs one background thread that wakes on
+  minute boundaries, iterates registered
+  :class:`~automation_file.scheduler.ScheduledJob` instances, and dispatches
+  every matching job on a short-lived worker thread so a slow action can't
+  starve subsequent jobs.
 
 Security boundaries
 -------------------
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 1d38b1c..15efdf9 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -176,6 +176,80 @@ SFTP specifically uses :class:`paramiko.RejectPolicy` — unknown hosts are
 rejected rather than auto-added. Provide ``known_hosts`` explicitly or rely on
 ``~/.ssh/known_hosts``.
 
+File-watcher triggers
+---------------------
+
+Run an action list whenever a filesystem event fires on a watched path. The
+module-level :data:`~automation_file.trigger.trigger_manager` keeps a named
+registry of active watchers so the JSON facade and the GUI share one
+lifecycle.
+
+.. code-block:: python
+
+   from automation_file import watch_start, watch_stop
+
+   watch_start(
+       name="inbox-sweeper",
+       path="/data/inbox",
+       action_list=[["FA_copy_all_file_to_dir", {"source_dir": "/data/inbox",
+                                                 "target_dir": "/data/processed"}]],
+       events=["created", "modified"],
+       recursive=False,
+   )
+   # later:
+   watch_stop("inbox-sweeper")
+
+Or drive it from a JSON action list with ``FA_watch_start`` /
+``FA_watch_stop`` / ``FA_watch_stop_all`` / ``FA_watch_list``.
+
+Cron scheduler
+--------------
+
+Run an action list on a recurring schedule. The 5-field cron parser supports
+``*``, exact values, ``a-b`` ranges, comma-separated lists, and ``*/n`` step
+syntax with ``jan``..``dec`` / ``sun``..``sat`` aliases.
+
+.. code-block:: python
+
+   from automation_file import schedule_add
+
+   schedule_add(
+       name="nightly-snapshot",
+       cron_expression="0 2 * * *",           # every day at 02:00 local time
+       action_list=[["FA_zip_dir", {"dir_we_want_to_zip": "/data",
+                                    "zip_name": "/backup/data_nightly"}]],
+   )
+
+A background thread wakes on minute boundaries, so expressions with
+sub-minute precision are not supported. Use ``FA_schedule_add`` /
+``FA_schedule_remove`` / ``FA_schedule_remove_all`` / ``FA_schedule_list``
+from JSON.
+
+Transfer progress + cancellation
+--------------------------------
+
+Pass ``progress_name="<label>"`` to :func:`download_file`,
+:func:`s3_upload_file`, or :func:`s3_download_file` to register the transfer
+with the shared progress registry. The GUI's **Progress** tab polls the
+registry every half second; ``FA_progress_list``, ``FA_progress_cancel``,
+and ``FA_progress_clear`` give JSON action lists the same view.
+
+.. code-block:: python
+
+   from automation_file import download_file, progress_cancel
+
+   # In one thread:
+   download_file("https://example.com/big.bin", "big.bin",
+                 progress_name="big-download")
+
+   # In another thread / from the GUI:
+   progress_cancel("big-download")
+
+Cancellation raises :class:`~automation_file.CancelledException` inside the
+transfer loop. The transfer function catches it, marks the reporter
+``status="cancelled"``, and returns ``False`` — callers don't need to handle
+the exception themselves.
+
 GUI (PySide6)
 -------------
 
@@ -193,7 +267,7 @@ A tabbed control surface wraps every feature:
 
    launch_ui()
 
-Tabs: Local, HTTP, Google Drive, S3, Azure Blob, Dropbox, SFTP, JSON actions,
+Tabs: Home, Local, Transfer, Progress, JSON actions, Triggers, Scheduler,
 Servers. A persistent log panel below the tabs streams every call's result or
 error. Background work runs on ``QThreadPool`` via ``ActionWorker`` so the UI
 stays responsive.

From 4d57b90b1702881c11fd2cb8706098eaa96b9c98 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 20:36:07 +0800
Subject: [PATCH 05/38] Add FA_fast_find: OS index fast path with scandir
 fallback

---
 README.md                               |  27 +++
 automation_file/__init__.py             |   4 +
 automation_file/core/action_registry.py |   7 +
 automation_file/utils/fast_find.py      | 227 ++++++++++++++++++++++++
 docs/source/api/utils.rst               |   3 +
 docs/source/architecture.rst            |   3 +-
 docs/source/usage.rst                   |  38 ++++
 tests/test_fast_find.py                 | 157 ++++++++++++++++
 8 files changed, 465 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/utils/fast_find.py
 create mode 100644 tests/test_fast_find.py

diff --git a/README.md b/README.md
index 310f636..f340e2d 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@ facade.
 - **File-watcher triggers** — run an action list whenever a path changes (`FA_watch_*`)
 - **Cron scheduler** — recurring action lists on a stdlib-only 5-field parser (`FA_schedule_*`)
 - **Transfer progress + cancellation** — opt-in `progress_name` hook on HTTP and S3 transfers (`FA_progress_*`)
+- **Fast file search** — OS index fast path (`mdfind` / `locate` / `es.exe`) with a streaming `scandir` fallback (`FA_fast_find`)
 - PySide6 GUI (`python -m automation_file ui`) with a tab per backend, the JSON-action runner, and dedicated tabs for Triggers, Scheduler, and live Progress
 - Rich CLI with one-shot subcommands plus legacy JSON-batch flags
 - Project scaffolding (`ProjectBuilder`) for executor-based automations
@@ -314,6 +315,32 @@ The shared `progress_registry` exposes live snapshots via `progress_list()`
 and the `FA_progress_list` / `FA_progress_cancel` / `FA_progress_clear` JSON
 actions. The GUI's **Progress** tab polls the registry every half second.
 
+### Fast file search
+Query an OS index when available (`mdfind` on macOS, `locate` / `plocate` on
+Linux, Everything's `es.exe` on Windows) and fall back to a streaming
+`os.scandir` walk otherwise. No extra dependencies.
+
+```python
+from automation_file import fast_find, scandir_find, has_os_index
+
+# Uses the OS indexer when available, scandir fallback otherwise.
+results = fast_find("/var/log", "*.log", limit=100)
+
+# Force the portable path (skip the OS indexer).
+results = fast_find("/data", "report_*.csv", use_index=False)
+
+# Streaming — stop early without scanning the whole tree.
+for path in scandir_find("/data", "*.csv"):
+    if "2026" in path:
+        break
+```
+
+`FA_fast_find` exposes the same function to JSON action lists:
+
+```json
+[["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
+```
+
 ### GUI
 ```bash
 python -m automation_file ui        # or: python main_ui.py
diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 240dd13..50bbb17 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -119,6 +119,7 @@
     watch_stop,
     watch_stop_all,
 )
+from automation_file.utils.fast_find import fast_find, has_os_index, scandir_find
 from automation_file.utils.file_discovery import get_dir_files_as_list
 
 if TYPE_CHECKING:
@@ -218,6 +219,9 @@ def __getattr__(name: str) -> Any:
     "ProjectBuilder",
     "create_project_dir",
     "get_dir_files_as_list",
+    "fast_find",
+    "scandir_find",
+    "has_os_index",
     # Triggers
     "FileWatcher",
     "TriggerManager",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 690ab85..99a6169 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -129,6 +129,12 @@ def _http_commands() -> dict[str, Command]:
     return {"FA_download_file": http_download.download_file}
 
 
+def _utils_commands() -> dict[str, Command]:
+    from automation_file.utils import fast_find
+
+    return {"FA_fast_find": fast_find.fast_find}
+
+
 def _register_cloud_backends(registry: ActionRegistry) -> None:
     from automation_file.remote.azure_blob import register_azure_blob_ops
     from automation_file.remote.dropbox_api import register_dropbox_ops
@@ -164,6 +170,7 @@ def build_default_registry() -> ActionRegistry:
     registry = ActionRegistry()
     registry.register_many(_local_commands())
     registry.register_many(_http_commands())
+    registry.register_many(_utils_commands())
     registry.register_many(_drive_commands())
     _register_cloud_backends(registry)
     _register_trigger_ops(registry)
diff --git a/automation_file/utils/fast_find.py b/automation_file/utils/fast_find.py
new file mode 100644
index 0000000..fd6bdc2
--- /dev/null
+++ b/automation_file/utils/fast_find.py
@@ -0,0 +1,227 @@
+"""Fast file search with OS-index fast path and scandir fallback.
+
+The module picks the cheapest backend available on the host:
+
+* macOS   — ``mdfind`` (Spotlight) when the search root is an indexed volume.
+* Linux   — ``locate`` / ``plocate`` when present and a recent database exists.
+* Windows — Everything's ``es.exe`` CLI when installed and running.
+* Fallback — a streaming ``os.scandir`` walk with ``fnmatch`` matching.
+
+Only the built-in ``os`` / ``fnmatch`` / ``subprocess`` / ``shutil`` stdlib
+modules are used — no extra dependencies. Results are returned as absolute
+path strings. The OS-index path is preferred because it avoids touching the
+filesystem at all; the fallback yields lazily and supports an early-termination
+``limit=`` so large trees don't waste energy after the caller has what it
+needs.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import platform
+import shutil
+import subprocess
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+
+from automation_file.logging_config import file_automation_logger
+
+__all__ = [
+    "fast_find",
+    "scandir_find",
+    "has_os_index",
+]
+
+_INDEX_TIMEOUT_SECONDS = 15
+_DEFAULT_PATTERN = "*"
+
+
+def has_os_index() -> str | None:
+    """Return the name of an available OS indexer (``mdfind`` / ``locate`` / ``es``) or ``None``."""
+    system = platform.system()
+    if system == "Darwin" and shutil.which("mdfind"):
+        return "mdfind"
+    if system == "Linux":
+        for candidate in ("plocate", "locate"):
+            if shutil.which(candidate):
+                return candidate
+    if system == "Windows" and shutil.which("es"):
+        return "es"
+    return None
+
+
+def fast_find(
+    root: str | os.PathLike[str],
+    pattern: str = _DEFAULT_PATTERN,
+    *,
+    limit: int | None = None,
+    files_only: bool = True,
+    use_index: bool = True,
+) -> list[str]:
+    """Return absolute paths under ``root`` matching ``pattern``.
+
+    ``pattern`` is a shell-style glob (``*.log``, ``report_*.csv``).
+    ``limit`` caps the number of results. ``files_only`` skips directories.
+    When ``use_index`` is true and an OS indexer is available the query is
+    dispatched to it; otherwise the scandir fallback runs.
+
+    The OS indexer is only used when it can honour the scope: ``mdfind``
+    accepts ``-onlyin``, ``locate`` / ``plocate`` accept a bare prefix match,
+    and ``es.exe`` accepts a ``path:`` query. If the indexer fails or is
+    restricted, the function silently falls back to scandir — no exception is
+    raised for the user.
+    """
+    root_path = Path(root).expanduser().resolve()
+    if not root_path.exists():
+        return []
+
+    if use_index:
+        indexer = has_os_index()
+        if indexer:
+            try:
+                results = _run_indexer(indexer, root_path, pattern, files_only, limit)
+            except (OSError, subprocess.SubprocessError) as err:
+                file_automation_logger.debug(
+                    "fast_find: indexer %s failed, falling back: %s", indexer, err
+                )
+            else:
+                if results is not None:
+                    return results
+
+    return list(scandir_find(root_path, pattern, limit=limit, files_only=files_only))
+
+
+def scandir_find(
+    root: str | os.PathLike[str],
+    pattern: str = _DEFAULT_PATTERN,
+    *,
+    limit: int | None = None,
+    files_only: bool = True,
+) -> Iterator[str]:
+    """Yield absolute paths under ``root`` matching ``pattern`` (streaming scandir).
+
+    This is the pure-Python fallback. It is the fastest *portable* strategy
+    when no OS index is available: ``os.scandir`` reads each directory once
+    and avoids the extra stat calls that ``os.walk`` / ``Path.rglob`` make.
+    Yielding rather than materialising lets the caller stop early via
+    ``limit=`` or by breaking out of the loop.
+    """
+    root_path = Path(root).expanduser().resolve()
+    if not root_path.exists():
+        return
+    yielded = 0
+    stack: list[str] = [str(root_path)]
+    lowered_pattern = pattern.lower()
+    while stack:
+        current = stack.pop()
+        try:
+            iterator = os.scandir(current)
+        except (PermissionError, FileNotFoundError, OSError):
+            continue
+        with iterator as entries:
+            for entry in entries:
+                try:
+                    is_dir = entry.is_dir(follow_symlinks=False)
+                except OSError:
+                    continue
+                if is_dir:
+                    stack.append(entry.path)
+                    if files_only:
+                        continue
+                if _matches(entry.name, lowered_pattern):
+                    yield os.path.abspath(entry.path)
+                    yielded += 1
+                    if limit is not None and yielded >= limit:
+                        return
+
+
+def _matches(name: str, lowered_pattern: str) -> bool:
+    return fnmatch.fnmatchcase(name.lower(), lowered_pattern)
+
+
+def _run_indexer(
+    indexer: str,
+    root: Path,
+    pattern: str,
+    files_only: bool,
+    limit: int | None,
+) -> list[str] | None:
+    if indexer == "mdfind":
+        return _run_mdfind(root, pattern, files_only, limit)
+    if indexer in ("locate", "plocate"):
+        return _run_locate(indexer, root, pattern, files_only, limit)
+    if indexer == "es":
+        return _run_everything(root, pattern, files_only, limit)
+    return None
+
+
+def _capture(argv: list[str]) -> list[str]:
+    completed = subprocess.run(
+        argv,
+        capture_output=True,
+        timeout=_INDEX_TIMEOUT_SECONDS,
+        check=False,
+    )
+    if completed.returncode not in (0, 1):
+        raise subprocess.SubprocessError(f"{argv[0]} exited with {completed.returncode}")
+    text = completed.stdout.decode("utf-8", errors="replace")
+    return [line for line in text.splitlines() if line]
+
+
+def _run_mdfind(root: Path, pattern: str, files_only: bool, limit: int | None) -> list[str]:
+    query = f'kMDItemFSName == "{pattern}"'
+    if files_only:
+        query += " && kMDItemContentType != 'public.folder'"
+    lines = _capture(["mdfind", "-onlyin", str(root), query])
+    return _post_filter(lines, root, pattern, files_only, limit)
+
+
+def _run_locate(
+    indexer: str, root: Path, pattern: str, files_only: bool, limit: int | None
+) -> list[str]:
+    lines = _capture([indexer, "-i", pattern])
+    prefix = str(root)
+    scoped = [line for line in lines if line.startswith(prefix)]
+    return _post_filter(scoped, root, pattern, files_only, limit)
+
+
+def _run_everything(root: Path, pattern: str, files_only: bool, limit: int | None) -> list[str]:
+    argv = ["es", "-path", str(root), pattern]
+    if files_only:
+        argv.append("/a-d")
+    if limit is not None:
+        argv.extend(["-n", str(limit)])
+    lines = _capture(argv)
+    return _post_filter(lines, root, pattern, files_only, limit)
+
+
+def _post_filter(
+    lines: Iterable[str],
+    root: Path,
+    pattern: str,
+    files_only: bool,
+    limit: int | None,
+) -> list[str]:
+    out: list[str] = []
+    lowered_pattern = pattern.lower()
+    for raw in lines:
+        path = Path(raw)
+        if not _is_within(root, path):
+            continue
+        if files_only and path.is_dir():
+            continue
+        if not _matches(path.name, lowered_pattern):
+            continue
+        out.append(str(path))
+        if limit is not None and len(out) >= limit:
+            break
+    return out
+
+
+def _is_within(root: Path, candidate: Path) -> bool:
+    try:
+        candidate.resolve().relative_to(root)
+    except (ValueError, OSError):
+        return False
+    return True
diff --git a/docs/source/api/utils.rst b/docs/source/api/utils.rst
index 7f6f12b..a4e7876 100644
--- a/docs/source/api/utils.rst
+++ b/docs/source/api/utils.rst
@@ -3,3 +3,6 @@ Utils
 
 .. automodule:: automation_file.utils.file_discovery
    :members:
+
+.. automodule:: automation_file.utils.fast_find
+   :members:
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
index 1ea85d3..6f7235f 100644
--- a/docs/source/architecture.rst
+++ b/docs/source/architecture.rst
@@ -87,7 +87,8 @@ Module layout
    │   ├── log_widget.py        # LogPanel
    │   └── tabs/                # one tab per backend + JSON runner + servers
    └── utils/
-       └── file_discovery.py
+       ├── file_discovery.py
+       └── fast_find.py         # OS-index (mdfind/locate/es) + scandir fallback
 
 Execution modes
 ---------------
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 15efdf9..23eaaa3 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -250,6 +250,44 @@ transfer loop. The transfer function catches it, marks the reporter
 ``status="cancelled"``, and returns ``False`` — callers don't need to handle
 the exception themselves.
 
+Fast file search
+----------------
+
+:func:`fast_find` picks the cheapest backend available on the host — OS
+index first, streaming scandir walk as a fallback — so large trees are
+searched with minimal energy:
+
+* macOS: ``mdfind`` (Spotlight)
+* Linux: ``plocate`` / ``locate`` database
+* Windows: Everything's ``es.exe`` CLI, if installed
+* Fallback: ``os.scandir`` generator with ``fnmatch`` matching and early
+  termination via ``limit=``
+
+.. code-block:: python
+
+   from automation_file import fast_find, scandir_find, has_os_index
+
+   # Query an indexer when available, fall back to scandir otherwise.
+   results = fast_find("/var/log", "*.log", limit=100)
+
+   # Force the portable path (skip the OS indexer).
+   results = fast_find("/data", "report_*.csv", use_index=False)
+
+   # Streaming generator — stop early without scanning the whole tree.
+   for path in scandir_find("/data", "*.csv"):
+       if "2026" in path:
+           break
+
+   # Which indexer will fast_find try?  Returns "mdfind" / "locate" /
+   # "plocate" / "es" / None.
+   has_os_index()
+
+The same action is available to JSON action lists as ``FA_fast_find``:
+
+.. code-block:: json
+
+   [["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
+
 GUI (PySide6)
 -------------
 
diff --git a/tests/test_fast_find.py b/tests/test_fast_find.py
new file mode 100644
index 0000000..c700a0c
--- /dev/null
+++ b/tests/test_fast_find.py
@@ -0,0 +1,157 @@
+"""Tests for automation_file.utils.fast_find."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from automation_file.utils import fast_find as ff
+from automation_file.utils.fast_find import fast_find, has_os_index, scandir_find
+
+
+def _seed(tmp_path: Path) -> None:
+    (tmp_path / "a.log").write_text("a", encoding="utf-8")
+    (tmp_path / "b.log").write_text("b", encoding="utf-8")
+    (tmp_path / "c.txt").write_text("c", encoding="utf-8")
+    nested = tmp_path / "nested"
+    nested.mkdir()
+    (nested / "d.log").write_text("d", encoding="utf-8")
+    (nested / "e.txt").write_text("e", encoding="utf-8")
+    deep = nested / "deep"
+    deep.mkdir()
+    (deep / "f.log").write_text("f", encoding="utf-8")
+
+
+def test_scandir_find_lists_all_files_by_default(tmp_path: Path) -> None:
+    _seed(tmp_path)
+    names = sorted(Path(p).name for p in scandir_find(tmp_path))
+    assert names == ["a.log", "b.log", "c.txt", "d.log", "e.txt", "f.log"]
+
+
+def test_scandir_find_glob_pattern(tmp_path: Path) -> None:
+    _seed(tmp_path)
+    names = sorted(Path(p).name for p in scandir_find(tmp_path, "*.log"))
+    assert names == ["a.log", "b.log", "d.log", "f.log"]
+
+
+def test_scandir_find_is_case_insensitive(tmp_path: Path) -> None:
+    (tmp_path / "X.LOG").write_text("x", encoding="utf-8")
+    names = [Path(p).name for p in scandir_find(tmp_path, "*.log")]
+    assert names == ["X.LOG"]
+
+
+def test_scandir_find_respects_limit(tmp_path: Path) -> None:
+    _seed(tmp_path)
+    results = list(scandir_find(tmp_path, "*.log", limit=2))
+    assert len(results) == 2
+
+
+def test_scandir_find_streams_lazily(tmp_path: Path) -> None:
+    _seed(tmp_path)
+    iterator = scandir_find(tmp_path, "*.log")
+    first = next(iterator)
+    assert first.endswith(".log")
+
+
+def test_scandir_find_includes_dirs_when_requested(tmp_path: Path) -> None:
+    _seed(tmp_path)
+    names = {Path(p).name for p in scandir_find(tmp_path, "*", files_only=False)}
+    assert "nested" in names
+    assert "deep" in names
+    assert "a.log" in names
+
+
+def test_scandir_find_returns_absolute_paths(tmp_path: Path) -> None:
+    _seed(tmp_path)
+    for path in scandir_find(tmp_path, "*.log"):
+        assert Path(path).is_absolute()
+
+
+def test_scandir_find_handles_missing_root(tmp_path: Path) -> None:
+    assert list(scandir_find(tmp_path / "does-not-exist")) == []
+
+
+def test_fast_find_falls_back_to_scandir_when_index_disabled(tmp_path: Path) -> None:
+    _seed(tmp_path)
+    names = sorted(Path(p).name for p in fast_find(tmp_path, "*.log", use_index=False))
+    assert names == ["a.log", "b.log", "d.log", "f.log"]
+
+
+def test_fast_find_returns_empty_for_missing_root(tmp_path: Path) -> None:
+    assert fast_find(tmp_path / "missing") == []
+
+
+def test_fast_find_respects_limit(tmp_path: Path) -> None:
+    _seed(tmp_path)
+    results = fast_find(tmp_path, "*.log", limit=1, use_index=False)
+    assert len(results) == 1
+
+
+def test_fast_find_files_only_excludes_dirs(tmp_path: Path) -> None:
+    _seed(tmp_path)
+    results = fast_find(tmp_path, "*", use_index=False, files_only=True)
+    assert all(Path(p).is_file() for p in results)
+
+
+def test_has_os_index_returns_str_or_none() -> None:
+    result = has_os_index()
+    assert result is None or isinstance(result, str)
+
+
+def test_fast_find_skips_unreadable_dirs(tmp_path: Path, monkeypatch) -> None:
+    _seed(tmp_path)
+    original_scandir = ff.os.scandir
+
+    def guarded(path: str):
+        if path.endswith("deep"):
+            raise PermissionError("denied")
+        return original_scandir(path)
+
+    monkeypatch.setattr(ff.os, "scandir", guarded)
+    names = sorted(Path(p).name for p in scandir_find(tmp_path, "*.log"))
+    assert "f.log" not in names
+    assert "a.log" in names
+
+
+def test_fast_find_registered_in_default_registry() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    registry = build_default_registry()
+    assert "FA_fast_find" in registry
+
+
+def test_fast_find_falls_back_when_indexer_raises(tmp_path: Path, monkeypatch) -> None:
+    _seed(tmp_path)
+    monkeypatch.setattr(ff, "has_os_index", lambda: "mdfind")
+
+    def boom(*_args, **_kwargs):
+        raise OSError("indexer not allowed")
+
+    monkeypatch.setattr(ff, "_run_indexer", boom)
+    results = fast_find(tmp_path, "*.log")
+    assert sorted(Path(p).name for p in results) == ["a.log", "b.log", "d.log", "f.log"]
+
+
+def test_fast_find_uses_indexer_when_available(tmp_path: Path, monkeypatch) -> None:
+    _seed(tmp_path)
+    monkeypatch.setattr(ff, "has_os_index", lambda: "locate")
+    canned = [str(tmp_path / "a.log"), str(tmp_path / "nested" / "d.log")]
+    monkeypatch.setattr(ff, "_run_indexer", lambda *_a, **_kw: canned)
+    results = fast_find(tmp_path, "*.log")
+    assert results == canned
+
+
+@pytest.mark.parametrize("indexer", ["mdfind", "plocate", "locate", "es"])
+def test_run_indexer_dispatches(tmp_path: Path, monkeypatch, indexer: str) -> None:
+    captured: dict[str, object] = {}
+
+    def fake_capture(argv: list[str]) -> list[str]:
+        captured["argv"] = argv
+        return [str(tmp_path / "a.log")]
+
+    (tmp_path / "a.log").write_text("a", encoding="utf-8")
+    monkeypatch.setattr(ff, "_capture", fake_capture)
+    result = ff._run_indexer(indexer, tmp_path, "*.log", True, None)
+    assert result == [str(tmp_path / "a.log")]
+    assert captured["argv"][0] == indexer

From 196f812da4d7a75c26ce2803e089d67fd74212d6 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 20:41:34 +0800
Subject: [PATCH 06/38] Add Traditional and Simplified Chinese README
 translations

---
 README.md       |   2 +
 README.zh-CN.md | 405 ++++++++++++++++++++++++++++++++++++++++++++++++
 README.zh-TW.md | 405 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 812 insertions(+)
 create mode 100644 README.zh-CN.md
 create mode 100644 README.zh-TW.md

diff --git a/README.md b/README.md
index f340e2d..9087906 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 # FileAutomation
 
+**English** | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
+
 A modular automation framework for local file / directory / ZIP operations,
 SSRF-validated HTTP downloads, remote storage (Google Drive, S3, Azure Blob,
 Dropbox, SFTP), and JSON-driven action execution over embedded TCP / HTTP
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 0000000..632be63
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,405 @@
+# FileAutomation
+
+[English](README.md) | [繁體中文](README.zh-TW.md) | **简体中文**
+
+一套模块化的自动化框架，涵盖本地文件 / 目录 / ZIP 操作、经 SSRF 验证的 HTTP
+下载、远程存储（Google Drive、S3、Azure Blob、Dropbox、SFTP），以及通过内嵌
+TCP / HTTP 服务器执行的 JSON 驱动动作。内附 PySide6 GUI，每个功能都有对应
+页签。所有公开 API 均由顶层 `automation_file` facade 统一导出。
+
+- 本地文件 / 目录 / ZIP 操作，内置路径穿越防护（`safe_join`）
+- 经 SSRF 验证的 HTTP 下载，支持重试与大小 / 时间上限
+- Google Drive CRUD（上传、下载、搜索、删除、分享、文件夹）
+- 一等公民的 S3、Azure Blob、Dropbox、SFTP 后端 — 默认安装
+- JSON 动作清单由共享的 `ActionExecutor` 执行 — 支持验证、干跑、并行
+- Loopback 优先的 TCP **与** HTTP 服务器，接受 JSON 指令批量并可选 shared-secret 验证
+- 可靠性原语：`retry_on_transient` 装饰器、`Quota` 大小 / 时间预算
+- **文件监听触发** — 当路径变动时执行动作清单（`FA_watch_*`）
+- **Cron 调度器** — 仅用标准库的 5 字段解析器执行周期性动作清单（`FA_schedule_*`）
+- **传输进度 + 取消** — HTTP 与 S3 传输可选的 `progress_name` 钩子（`FA_progress_*`）
+- **快速文件搜索** — OS 索引快速路径（`mdfind` / `locate` / `es.exe`）搭配流式 `scandir` 回退（`FA_fast_find`）
+- PySide6 GUI（`python -m automation_file ui`）每个后端一个页签，含 JSON 动作执行器，另有 Triggers、Scheduler、实时 Progress 专属页签
+- 功能丰富的 CLI，包含一次性子命令与旧式 JSON 批量标志
+- 项目脚手架（`ProjectBuilder`）协助构建以 executor 为核心的自动化项目
+
+## 架构
+
+```mermaid
+flowchart LR
+    User[User / CLI / JSON batch]
+
+    subgraph Facade["automation_file (facade)"]
+        Public["Public API<br/>execute_action, execute_action_parallel,<br/>validate_action, driver_instance,<br/>start_autocontrol_socket_server,<br/>start_http_action_server, Quota,<br/>retry_on_transient, safe_join, ..."]
+    end
+
+    subgraph Core["core"]
+        Registry[(ActionRegistry<br/>FA_* commands)]
+        Executor[ActionExecutor]
+        Callback[CallbackExecutor]
+        Loader[PackageLoader]
+        Json[json_store]
+        Retry[retry]
+        QuotaMod[quota]
+        Progress[progress<br/>Token + Reporter]
+    end
+
+    subgraph Events["event-driven"]
+        TriggerMod["trigger<br/>watchdog file watcher"]
+        SchedulerMod["scheduler<br/>cron background thread"]
+    end
+
+    subgraph Local["local"]
+        FileOps[file_ops]
+        DirOps[dir_ops]
+        ZipOps[zip_ops]
+        Safe[safe_paths]
+    end
+
+    subgraph Remote["remote"]
+        UrlVal[url_validator]
+        Http[http_download]
+        Drive["google_drive<br/>client + *_ops"]
+        S3["s3"]
+        Azure["azure_blob"]
+        Dropbox["dropbox_api"]
+        SFTP["sftp"]
+    end
+
+    subgraph Server["server"]
+        TCP[TCPActionServer]
+        HTTP[HTTPActionServer]
+    end
+
+    subgraph UI["ui (PySide6)"]
+        Launcher[launch_ui]
+        MainWindow["MainWindow<br/>9-tab control surface"]
+    end
+
+    subgraph Project["project / utils"]
+        Builder[ProjectBuilder]
+        Templates[templates]
+        Discovery[file_discovery]
+    end
+
+    User --> Public
+    User --> Launcher
+    Launcher --> MainWindow
+    MainWindow --> Public
+    Public --> Executor
+    Public --> Callback
+    Public --> Loader
+    Public --> TCP
+    Public --> HTTP
+
+    Executor --> Registry
+    Executor --> Retry
+    Executor --> QuotaMod
+    Callback --> Registry
+    Loader --> Registry
+    TCP --> Executor
+    HTTP --> Executor
+    Executor --> Json
+
+    Registry --> FileOps
+    Registry --> DirOps
+    Registry --> ZipOps
+    Registry --> Safe
+    Registry --> Http
+    Registry --> Drive
+    Registry --> S3
+    Registry --> Azure
+    Registry --> Dropbox
+    Registry --> SFTP
+    Registry --> Builder
+    Registry --> TriggerMod
+    Registry --> SchedulerMod
+    Registry --> Progress
+
+    TriggerMod --> Executor
+    SchedulerMod --> Executor
+    Http --> Progress
+    S3 --> Progress
+
+    Http --> UrlVal
+    Http --> Retry
+    Builder --> Templates
+    Builder --> Discovery
+```
+
+`build_default_registry()` 构建的 `ActionRegistry` 是所有 `FA_*` 命令的唯一
+权威来源。`ActionExecutor`、`CallbackExecutor`、`PackageLoader`、
+`TCPActionServer`、`HTTPActionServer` 都通过同一份共享 registry（以
+`executor.registry` 对外公开）解析命令。
+
+## 安装
+
+```bash
+pip install automation_file
+```
+
+单次安装即涵盖所有后端（Google Drive、S3、Azure Blob、Dropbox、SFTP）以及
+PySide6 GUI — 日常使用不需要任何 extras。
+
+```bash
+pip install "automation_file[dev]"       # ruff, mypy, pre-commit, pytest-cov, build, twine
+```
+
+要求：
+- Python 3.10+
+- 内置依赖：`google-api-python-client`、`google-auth-oauthlib`、
+  `requests`、`tqdm`、`boto3`、`azure-storage-blob`、`dropbox`、`paramiko`、
+  `PySide6`、`watchdog`
+
+## 使用方式
+
+### 执行 JSON 动作清单
+```python
+from automation_file import execute_action
+
+execute_action([
+    ["FA_create_file", {"file_path": "test.txt"}],
+    ["FA_copy_file", {"source": "test.txt", "target": "copy.txt"}],
+])
+```
+
+### 验证、干跑、并行
+```python
+from automation_file import execute_action, execute_action_parallel, validate_action
+
+# Fail-fast：只要有任何命令名称未知就在执行前中止。
+execute_action(actions, validate_first=True)
+
+# Dry-run：只记录会被调用的内容，不真的执行。
+execute_action(actions, dry_run=True)
+
+# Parallel：通过 thread pool 并行执行独立动作。
+execute_action_parallel(actions, max_workers=4)
+
+# 手动验证 — 返回解析后的名称列表。
+names = validate_action(actions)
+```
+
+### 初始化 Google Drive 并上传
+```python
+from automation_file import driver_instance, drive_upload_to_drive
+
+driver_instance.later_init("token.json", "credentials.json")
+drive_upload_to_drive("example.txt")
+```
+
+### 经验证的 HTTP 下载（含重试）
+```python
+from automation_file import download_file
+
+download_file("https://example.com/file.zip", "file.zip")
+```
+
+### 启动 loopback TCP 服务器（可选 shared-secret 验证）
+```python
+from automation_file import start_autocontrol_socket_server
+
+server = start_autocontrol_socket_server(
+    host="127.0.0.1", port=9943, shared_secret="optional-secret",
+)
+```
+
+设定 `shared_secret` 时，客户端每个包都必须以 `AUTH <secret>\n` 为前缀。
+若要绑定非 loopback 地址必须明确传入 `allow_non_loopback=True`。
+
+### 启动 HTTP 动作服务器
+```python
+from automation_file import start_http_action_server
+
+server = start_http_action_server(
+    host="127.0.0.1", port=9944, shared_secret="optional-secret",
+)
+
+# curl -H 'Authorization: Bearer optional-secret' \
+#      -d '[["FA_create_dir",{"dir_path":"x"}]]' \
+#      http://127.0.0.1:9944/actions
+```
+
+### Retry 与 quota 原语
+```python
+from automation_file import retry_on_transient, Quota
+
+@retry_on_transient(max_attempts=5, backoff_base=0.5)
+def flaky_network_call(): ...
+
+quota = Quota(max_bytes=50 * 1024 * 1024, max_seconds=30.0)
+with quota.time_budget("bulk-upload"):
+    bulk_upload_work()
+```
+
+### 路径穿越防护
+```python
+from automation_file import safe_join
+
+target = safe_join("/data/jobs", user_supplied_path)
+# 若解析后的路径逃出 /data/jobs 会抛出 PathTraversalException。
+```
+
+### Cloud / SFTP 后端
+每个后端都会由 `build_default_registry()` 自动注册，因此 `FA_s3_*`、
+`FA_azure_blob_*`、`FA_dropbox_*`、`FA_sftp_*` 动作开箱即用 — 不需要另外调用
+`register_*_ops`。
+
+```python
+from automation_file import execute_action, s3_instance
+
+s3_instance.later_init(region_name="us-east-1")
+
+execute_action([
+    ["FA_s3_upload_file", {"local_path": "report.csv", "bucket": "reports", "key": "report.csv"}],
+])
+```
+
+所有后端（`s3`、`azure_blob`、`dropbox_api`、`sftp`）都提供相同的五组操作：
+`upload_file`、`upload_dir`、`download_file`、`delete_*`、`list_*`。
+SFTP 使用 `paramiko.RejectPolicy` — 未知主机会被拒绝，不会自动加入。
+
+### 文件监听触发
+每当被监听路径发生文件系统事件，就执行动作清单：
+
+```python
+from automation_file import watch_start, watch_stop
+
+watch_start(
+    name="inbox-sweeper",
+    path="/data/inbox",
+    action_list=[["FA_copy_all_file_to_dir", {"source_dir": "/data/inbox",
+                                              "target_dir": "/data/processed"}]],
+    events=["created", "modified"],
+    recursive=False,
+)
+# 稍后：
+watch_stop("inbox-sweeper")
+```
+
+`FA_watch_start` / `FA_watch_stop` / `FA_watch_stop_all` / `FA_watch_list`
+让 JSON 动作清单能使用相同的生命周期。
+
+### Cron 调度器
+以纯标准库的 5 字段 cron 解析器执行周期性动作清单：
+
+```python
+from automation_file import schedule_add
+
+schedule_add(
+    name="nightly-snapshot",
+    cron_expression="0 2 * * *",        # 每天本地时间 02:00
+    action_list=[["FA_zip_dir", {"dir_we_want_to_zip": "/data",
+                                 "zip_name": "/backup/data_nightly"}]],
+)
+```
+
+支持 `*`、确切值、`a-b` 范围、逗号列表、`*/n` 步进语法，以及 `jan..dec` /
+`sun..sat` 别名。JSON 动作：`FA_schedule_add`、`FA_schedule_remove`、
+`FA_schedule_remove_all`、`FA_schedule_list`。
+
+### 传输进度 + 取消
+HTTP 与 S3 传输支持可选的 `progress_name` 关键字参数：
+
+```python
+from automation_file import download_file, progress_cancel
+
+download_file("https://example.com/big.bin", "big.bin",
+              progress_name="big-download")
+
+# 从另一个线程或 GUI：
+progress_cancel("big-download")
+```
+
+共享的 `progress_registry` 通过 `progress_list()` 以及 `FA_progress_list` /
+`FA_progress_cancel` / `FA_progress_clear` JSON 动作提供实时快照。GUI 的
+**Progress** 页签每半秒轮询一次 registry。
+
+### 快速文件搜索
+若 OS 索引器可用就直接查询（macOS 的 `mdfind`、Linux 的 `locate` /
+`plocate`、Windows 的 Everything `es.exe`），否则回退到以流式 `os.scandir`
+遍历。不需要额外依赖。
+
+```python
+from automation_file import fast_find, scandir_find, has_os_index
+
+# 可用时使用 OS 索引器，否则回退到 scandir。
+results = fast_find("/var/log", "*.log", limit=100)
+
+# 强制使用可移植路径（跳过 OS 索引器）。
+results = fast_find("/data", "report_*.csv", use_index=False)
+
+# 流式 — 不需要遍历整棵树就能提前停止。
+for path in scandir_find("/data", "*.csv"):
+    if "2026" in path:
+        break
+```
+
+`FA_fast_find` 将同一个函数提供给 JSON 动作清单：
+
+```json
+[["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
+```
+
+### GUI
+```bash
+python -m automation_file ui        # 或：python main_ui.py
+```
+
+```python
+from automation_file import launch_ui
+launch_ui()
+```
+
+页签：Home、Local、Transfer、Progress、JSON actions、Triggers、Scheduler、
+Servers。底部常驻的 log 面板实时流式输出每一笔结果与错误。
+
+### 以 executor 为核心构建项目脚手架
+```python
+from automation_file import create_project_dir
+
+create_project_dir("my_workflow")
+```
+
+## CLI
+
+```bash
+# 子命令（一次性操作）
+python -m automation_file ui
+python -m automation_file zip ./src out.zip --dir
+python -m automation_file unzip out.zip ./restored
+python -m automation_file download https://example.com/file.bin file.bin
+python -m automation_file create-file hello.txt --content "hi"
+python -m automation_file server --host 127.0.0.1 --port 9943
+python -m automation_file http-server --host 127.0.0.1 --port 9944
+python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
+
+# 旧式标志（JSON 动作清单）
+python -m automation_file --execute_file actions.json
+python -m automation_file --execute_dir ./actions/
+python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
+python -m automation_file --create_project ./my_project
+```
+
+## JSON 动作格式
+
+每一项动作可以是单纯的命令名称、`[name, kwargs]` 组合，或 `[name, args]`
+列表：
+
+```json
+[
+  ["FA_create_file", {"file_path": "test.txt"}],
+  ["FA_drive_upload_to_drive", {"file_path": "test.txt"}],
+  ["FA_drive_search_all_file"]
+]
+```
+
+## 文档
+
+完整 API 文档位于 `docs/`，可用 Sphinx 生成：
+
+```bash
+pip install -r docs/requirements.txt
+sphinx-build -b html docs/source docs/_build/html
+```
+
+架构笔记、代码规范与安全考量请参见 [`CLAUDE.md`](CLAUDE.md)。
diff --git a/README.zh-TW.md b/README.zh-TW.md
new file mode 100644
index 0000000..6fcc4b3
--- /dev/null
+++ b/README.zh-TW.md
@@ -0,0 +1,405 @@
+# FileAutomation
+
+[English](README.md) | **繁體中文** | [简体中文](README.zh-CN.md)
+
+一套模組化的自動化框架，涵蓋本機檔案 / 目錄 / ZIP 操作、經 SSRF 驗證的 HTTP
+下載、遠端儲存（Google Drive、S3、Azure Blob、Dropbox、SFTP），以及透過內建
+TCP / HTTP 伺服器執行的 JSON 驅動動作。內附 PySide6 GUI，每個功能都有對應
+分頁。所有公開 API 皆由頂層 `automation_file` facade 統一匯出。
+
+- 本機檔案 / 目錄 / ZIP 操作，內建路徑穿越防護（`safe_join`）
+- 經 SSRF 驗證的 HTTP 下載，支援重試與大小 / 時間上限
+- Google Drive CRUD（上傳、下載、搜尋、刪除、分享、資料夾）
+- 一等公民的 S3、Azure Blob、Dropbox、SFTP 後端 — 預設安裝
+- JSON 動作清單由共用的 `ActionExecutor` 執行 — 支援驗證、乾跑、平行
+- Loopback 優先的 TCP **與** HTTP 伺服器，接受 JSON 指令批次並可選 shared-secret 驗證
+- 可靠性原語：`retry_on_transient` 裝飾器、`Quota` 大小 / 時間預算
+- **檔案監看觸發** — 當路徑變動時執行動作清單（`FA_watch_*`）
+- **Cron 排程器** — 僅用標準函式庫的 5 欄位解析器執行週期性動作清單（`FA_schedule_*`）
+- **傳輸進度 + 取消** — HTTP 與 S3 傳輸可選的 `progress_name` 掛鉤（`FA_progress_*`）
+- **快速檔案搜尋** — OS 索引快速路徑（`mdfind` / `locate` / `es.exe`）搭配串流式 `scandir` 備援（`FA_fast_find`）
+- PySide6 GUI（`python -m automation_file ui`）每個後端一個分頁，含 JSON 動作執行器，另有 Triggers、Scheduler、即時 Progress 專屬分頁
+- 功能豐富的 CLI，包含一次性子指令與舊式 JSON 批次旗標
+- 專案鷹架（`ProjectBuilder`）協助建立以 executor 為核心的自動化專案
+
+## 架構
+
+```mermaid
+flowchart LR
+    User[User / CLI / JSON batch]
+
+    subgraph Facade["automation_file (facade)"]
+        Public["Public API<br/>execute_action, execute_action_parallel,<br/>validate_action, driver_instance,<br/>start_autocontrol_socket_server,<br/>start_http_action_server, Quota,<br/>retry_on_transient, safe_join, ..."]
+    end
+
+    subgraph Core["core"]
+        Registry[(ActionRegistry<br/>FA_* commands)]
+        Executor[ActionExecutor]
+        Callback[CallbackExecutor]
+        Loader[PackageLoader]
+        Json[json_store]
+        Retry[retry]
+        QuotaMod[quota]
+        Progress[progress<br/>Token + Reporter]
+    end
+
+    subgraph Events["event-driven"]
+        TriggerMod["trigger<br/>watchdog file watcher"]
+        SchedulerMod["scheduler<br/>cron background thread"]
+    end
+
+    subgraph Local["local"]
+        FileOps[file_ops]
+        DirOps[dir_ops]
+        ZipOps[zip_ops]
+        Safe[safe_paths]
+    end
+
+    subgraph Remote["remote"]
+        UrlVal[url_validator]
+        Http[http_download]
+        Drive["google_drive<br/>client + *_ops"]
+        S3["s3"]
+        Azure["azure_blob"]
+        Dropbox["dropbox_api"]
+        SFTP["sftp"]
+    end
+
+    subgraph Server["server"]
+        TCP[TCPActionServer]
+        HTTP[HTTPActionServer]
+    end
+
+    subgraph UI["ui (PySide6)"]
+        Launcher[launch_ui]
+        MainWindow["MainWindow<br/>9-tab control surface"]
+    end
+
+    subgraph Project["project / utils"]
+        Builder[ProjectBuilder]
+        Templates[templates]
+        Discovery[file_discovery]
+    end
+
+    User --> Public
+    User --> Launcher
+    Launcher --> MainWindow
+    MainWindow --> Public
+    Public --> Executor
+    Public --> Callback
+    Public --> Loader
+    Public --> TCP
+    Public --> HTTP
+
+    Executor --> Registry
+    Executor --> Retry
+    Executor --> QuotaMod
+    Callback --> Registry
+    Loader --> Registry
+    TCP --> Executor
+    HTTP --> Executor
+    Executor --> Json
+
+    Registry --> FileOps
+    Registry --> DirOps
+    Registry --> ZipOps
+    Registry --> Safe
+    Registry --> Http
+    Registry --> Drive
+    Registry --> S3
+    Registry --> Azure
+    Registry --> Dropbox
+    Registry --> SFTP
+    Registry --> Builder
+    Registry --> TriggerMod
+    Registry --> SchedulerMod
+    Registry --> Progress
+
+    TriggerMod --> Executor
+    SchedulerMod --> Executor
+    Http --> Progress
+    S3 --> Progress
+
+    Http --> UrlVal
+    Http --> Retry
+    Builder --> Templates
+    Builder --> Discovery
+```
+
+`build_default_registry()` 建立的 `ActionRegistry` 是所有 `FA_*` 指令的唯一
+權威來源。`ActionExecutor`、`CallbackExecutor`、`PackageLoader`、
+`TCPActionServer`、`HTTPActionServer` 都透過同一份共用 registry（以
+`executor.registry` 對外公開）解析指令。
+
+## 安裝
+
+```bash
+pip install automation_file
+```
+
+單一安裝即涵蓋所有後端（Google Drive、S3、Azure Blob、Dropbox、SFTP）以及
+PySide6 GUI — 日常使用不需要任何 extras。
+
+```bash
+pip install "automation_file[dev]"       # ruff, mypy, pre-commit, pytest-cov, build, twine
+```
+
+需求：
+- Python 3.10+
+- 內建相依套件：`google-api-python-client`、`google-auth-oauthlib`、
+  `requests`、`tqdm`、`boto3`、`azure-storage-blob`、`dropbox`、`paramiko`、
+  `PySide6`、`watchdog`
+
+## 使用方式
+
+### 執行 JSON 動作清單
+```python
+from automation_file import execute_action
+
+execute_action([
+    ["FA_create_file", {"file_path": "test.txt"}],
+    ["FA_copy_file", {"source": "test.txt", "target": "copy.txt"}],
+])
+```
+
+### 驗證、乾跑、平行
+```python
+from automation_file import execute_action, execute_action_parallel, validate_action
+
+# Fail-fast：只要有任何指令名稱未知就在執行前中止。
+execute_action(actions, validate_first=True)
+
+# Dry-run：只記錄會被呼叫的內容，不真的執行。
+execute_action(actions, dry_run=True)
+
+# Parallel：透過 thread pool 平行執行獨立動作。
+execute_action_parallel(actions, max_workers=4)
+
+# 手動驗證 — 回傳解析後的名稱清單。
+names = validate_action(actions)
+```
+
+### 初始化 Google Drive 並上傳
+```python
+from automation_file import driver_instance, drive_upload_to_drive
+
+driver_instance.later_init("token.json", "credentials.json")
+drive_upload_to_drive("example.txt")
+```
+
+### 經驗證的 HTTP 下載（含重試）
+```python
+from automation_file import download_file
+
+download_file("https://example.com/file.zip", "file.zip")
+```
+
+### 啟動 loopback TCP 伺服器（可選 shared-secret 驗證）
+```python
+from automation_file import start_autocontrol_socket_server
+
+server = start_autocontrol_socket_server(
+    host="127.0.0.1", port=9943, shared_secret="optional-secret",
+)
+```
+
+設定 `shared_secret` 時，客戶端每個封包都必須以 `AUTH <secret>\n` 為前綴。
+若要綁定非 loopback 位址必須明確傳入 `allow_non_loopback=True`。
+
+### 啟動 HTTP 動作伺服器
+```python
+from automation_file import start_http_action_server
+
+server = start_http_action_server(
+    host="127.0.0.1", port=9944, shared_secret="optional-secret",
+)
+
+# curl -H 'Authorization: Bearer optional-secret' \
+#      -d '[["FA_create_dir",{"dir_path":"x"}]]' \
+#      http://127.0.0.1:9944/actions
+```
+
+### Retry 與 quota 原語
+```python
+from automation_file import retry_on_transient, Quota
+
+@retry_on_transient(max_attempts=5, backoff_base=0.5)
+def flaky_network_call(): ...
+
+quota = Quota(max_bytes=50 * 1024 * 1024, max_seconds=30.0)
+with quota.time_budget("bulk-upload"):
+    bulk_upload_work()
+```
+
+### 路徑穿越防護
+```python
+from automation_file import safe_join
+
+target = safe_join("/data/jobs", user_supplied_path)
+# 若解析後的路徑跳脫 /data/jobs 會拋出 PathTraversalException。
+```
+
+### Cloud / SFTP 後端
+每個後端都會由 `build_default_registry()` 自動註冊，因此 `FA_s3_*`、
+`FA_azure_blob_*`、`FA_dropbox_*`、`FA_sftp_*` 動作開箱即用 — 不需要另外呼叫
+`register_*_ops`。
+
+```python
+from automation_file import execute_action, s3_instance
+
+s3_instance.later_init(region_name="us-east-1")
+
+execute_action([
+    ["FA_s3_upload_file", {"local_path": "report.csv", "bucket": "reports", "key": "report.csv"}],
+])
+```
+
+所有後端（`s3`、`azure_blob`、`dropbox_api`、`sftp`）都對外提供相同的五組
+操作：`upload_file`、`upload_dir`、`download_file`、`delete_*`、`list_*`。
+SFTP 使用 `paramiko.RejectPolicy` — 未知主機會被拒絕，不會自動加入。
+
+### 檔案監看觸發
+每當被監看路徑發生檔案系統事件，就執行動作清單：
+
+```python
+from automation_file import watch_start, watch_stop
+
+watch_start(
+    name="inbox-sweeper",
+    path="/data/inbox",
+    action_list=[["FA_copy_all_file_to_dir", {"source_dir": "/data/inbox",
+                                              "target_dir": "/data/processed"}]],
+    events=["created", "modified"],
+    recursive=False,
+)
+# 稍後：
+watch_stop("inbox-sweeper")
+```
+
+`FA_watch_start` / `FA_watch_stop` / `FA_watch_stop_all` / `FA_watch_list`
+讓 JSON 動作清單能使用相同的生命週期。
+
+### Cron 排程器
+以純標準函式庫的 5 欄位 cron 解析器執行週期性動作清單：
+
+```python
+from automation_file import schedule_add
+
+schedule_add(
+    name="nightly-snapshot",
+    cron_expression="0 2 * * *",        # 每天本地時間 02:00
+    action_list=[["FA_zip_dir", {"dir_we_want_to_zip": "/data",
+                                 "zip_name": "/backup/data_nightly"}]],
+)
+```
+
+支援 `*`、確切值、`a-b` 範圍、逗號清單、`*/n` 步進語法，以及 `jan..dec` /
+`sun..sat` 別名。JSON 動作：`FA_schedule_add`、`FA_schedule_remove`、
+`FA_schedule_remove_all`、`FA_schedule_list`。
+
+### 傳輸進度 + 取消
+HTTP 與 S3 傳輸支援可選的 `progress_name` 關鍵字參數：
+
+```python
+from automation_file import download_file, progress_cancel
+
+download_file("https://example.com/big.bin", "big.bin",
+              progress_name="big-download")
+
+# 從另一個執行緒或 GUI：
+progress_cancel("big-download")
+```
+
+共用的 `progress_registry` 透過 `progress_list()` 以及 `FA_progress_list` /
+`FA_progress_cancel` / `FA_progress_clear` JSON 動作提供即時快照。GUI 的
+**Progress** 分頁每半秒輪詢一次 registry。
+
+### 快速檔案搜尋
+若 OS 索引器可用就直接查詢（macOS 的 `mdfind`、Linux 的 `locate` /
+`plocate`、Windows 的 Everything `es.exe`），否則退回以串流 `os.scandir`
+走訪。不需要額外相依套件。
+
+```python
+from automation_file import fast_find, scandir_find, has_os_index
+
+# 可用時使用 OS 索引器，否則退回 scandir。
+results = fast_find("/var/log", "*.log", limit=100)
+
+# 強制使用可攜路徑（跳過 OS 索引器）。
+results = fast_find("/data", "report_*.csv", use_index=False)
+
+# 串流 — 不需走訪整棵樹就能提早停止。
+for path in scandir_find("/data", "*.csv"):
+    if "2026" in path:
+        break
+```
+
+`FA_fast_find` 將同一個函式提供給 JSON 動作清單：
+
+```json
+[["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
+```
+
+### GUI
+```bash
+python -m automation_file ui        # 或：python main_ui.py
+```
+
+```python
+from automation_file import launch_ui
+launch_ui()
+```
+
+分頁：Home、Local、Transfer、Progress、JSON actions、Triggers、Scheduler、
+Servers。底部常駐的 log 面板即時串流每一筆結果與錯誤。
+
+### 以 executor 為核心建立專案鷹架
+```python
+from automation_file import create_project_dir
+
+create_project_dir("my_workflow")
+```
+
+## CLI
+
+```bash
+# 子指令（一次性操作）
+python -m automation_file ui
+python -m automation_file zip ./src out.zip --dir
+python -m automation_file unzip out.zip ./restored
+python -m automation_file download https://example.com/file.bin file.bin
+python -m automation_file create-file hello.txt --content "hi"
+python -m automation_file server --host 127.0.0.1 --port 9943
+python -m automation_file http-server --host 127.0.0.1 --port 9944
+python -m automation_file drive-upload my.txt --token token.json --credentials creds.json
+
+# 舊式旗標（JSON 動作清單）
+python -m automation_file --execute_file actions.json
+python -m automation_file --execute_dir ./actions/
+python -m automation_file --execute_str '[["FA_create_dir",{"dir_path":"x"}]]'
+python -m automation_file --create_project ./my_project
+```
+
+## JSON 動作格式
+
+每一項動作可以是單純的指令名稱、`[name, kwargs]` 組合，或 `[name, args]`
+清單：
+
+```json
+[
+  ["FA_create_file", {"file_path": "test.txt"}],
+  ["FA_drive_upload_to_drive", {"file_path": "test.txt"}],
+  ["FA_drive_search_all_file"]
+]
+```
+
+## 文件
+
+完整 API 文件位於 `docs/`，可用 Sphinx 產生：
+
+```bash
+pip install -r docs/requirements.txt
+sphinx-build -b html docs/source docs/_build/html
+```
+
+架構筆記、程式碼慣例與安全考量請參見 [`CLAUDE.md`](CLAUDE.md)。

From 462caa0aa7c8fe9b373c35ea5a2604f42a502040 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 20:53:29 +0800
Subject: [PATCH 07/38] Add SHA-256 checksum helpers and resumable HTTP
 downloads

---
 automation_file/__init__.py             |   8 ++
 automation_file/core/action_registry.py |   7 +-
 automation_file/core/checksum.py        |  72 ++++++++++++++
 automation_file/remote/http_download.py |  63 +++++++++---
 tests/test_checksum.py                  |  80 ++++++++++++++++
 tests/test_http_download_resume.py      | 121 ++++++++++++++++++++++++
 6 files changed, 338 insertions(+), 13 deletions(-)
 create mode 100644 automation_file/core/checksum.py
 create mode 100644 tests/test_checksum.py
 create mode 100644 tests/test_http_download_resume.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 50bbb17..32872cb 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -20,6 +20,11 @@
 )
 from automation_file.core.action_registry import ActionRegistry, build_default_registry
 from automation_file.core.callback_executor import CallbackExecutor
+from automation_file.core.checksum import (
+    ChecksumMismatchException,
+    file_checksum,
+    verify_checksum,
+)
 from automation_file.core.json_store import read_action_json, write_action_json
 from automation_file.core.package_loader import PackageLoader
 from automation_file.core.progress import (
@@ -222,6 +227,9 @@ def __getattr__(name: str) -> Any:
     "fast_find",
     "scandir_find",
     "has_os_index",
+    "file_checksum",
+    "verify_checksum",
+    "ChecksumMismatchException",
     # Triggers
     "FileWatcher",
     "TriggerManager",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 99a6169..d0c2386 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -130,9 +130,14 @@ def _http_commands() -> dict[str, Command]:
 
 
 def _utils_commands() -> dict[str, Command]:
+    from automation_file.core import checksum
     from automation_file.utils import fast_find
 
-    return {"FA_fast_find": fast_find.fast_find}
+    return {
+        "FA_fast_find": fast_find.fast_find,
+        "FA_file_checksum": checksum.file_checksum,
+        "FA_verify_checksum": checksum.verify_checksum,
+    }
 
 
 def _register_cloud_backends(registry: ActionRegistry) -> None:
diff --git a/automation_file/core/checksum.py b/automation_file/core/checksum.py
new file mode 100644
index 0000000..69b5080
--- /dev/null
+++ b/automation_file/core/checksum.py
@@ -0,0 +1,72 @@
+"""File checksum + integrity verification helpers.
+
+Streaming hashes so multi-GB files don't blow up memory. The hash algorithm
+is whatever :func:`hashlib.new` understands (``sha256``, ``sha1``, ``md5``,
+``blake2b``, ...). :func:`file_checksum` returns the hex digest;
+:func:`verify_checksum` does a constant-time compare against the expected
+value so callers can't leak timing on the check.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+from pathlib import Path
+
+from automation_file.exceptions import FileAutomationException, FileNotExistsException
+from automation_file.logging_config import file_automation_logger
+
+__all__ = [
+    "ChecksumMismatchException",
+    "file_checksum",
+    "verify_checksum",
+]
+
+_DEFAULT_ALGO = "sha256"
+_DEFAULT_CHUNK = 1024 * 1024  # 1 MiB
+
+
+class ChecksumMismatchException(FileAutomationException):
+    """Raised when a computed digest does not match the expected value."""
+
+
+def file_checksum(
+    path: str | os.PathLike[str],
+    algorithm: str = _DEFAULT_ALGO,
+    chunk_size: int = _DEFAULT_CHUNK,
+) -> str:
+    """Return the hex digest of ``path`` under ``algorithm``.
+
+    Reads the file in ``chunk_size`` blocks so the memory cost is bounded
+    regardless of file size. Raises :class:`FileNotExistsException` when the
+    path is missing and :class:`ValueError` for unknown algorithms.
+    """
+    target = Path(path)
+    if not target.is_file():
+        raise FileNotExistsException(f"checksum target missing: {target}")
+    try:
+        digest = hashlib.new(algorithm)
+    except ValueError as err:
+        raise ValueError(f"unknown hash algorithm: {algorithm!r}") from err
+    with target.open("rb") as handle:
+        for block in iter(lambda: handle.read(chunk_size), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def verify_checksum(
+    path: str | os.PathLike[str],
+    expected: str,
+    algorithm: str = _DEFAULT_ALGO,
+    chunk_size: int = _DEFAULT_CHUNK,
+) -> bool:
+    """Return True iff ``path``'s digest matches ``expected`` (case-insensitive).
+
+    Uses :func:`hmac.compare_digest` so the match check is constant-time.
+    """
+    actual = file_checksum(path, algorithm=algorithm, chunk_size=chunk_size)
+    matched = hmac.compare_digest(actual.lower(), expected.lower())
+    if not matched:
+        file_automation_logger.warning("verify_checksum mismatch: %s algo=%s", path, algorithm)
+    return matched
diff --git a/automation_file/remote/http_download.py b/automation_file/remote/http_download.py
index 7c09489..4f135d0 100644
--- a/automation_file/remote/http_download.py
+++ b/automation_file/remote/http_download.py
@@ -2,9 +2,14 @@
 
 from __future__ import annotations
 
+import contextlib
+import os
+from pathlib import Path
+
 import requests
 from tqdm import tqdm
 
+from automation_file.core.checksum import verify_checksum
 from automation_file.core.progress import (
     CancelledException,
     ProgressReporter,
@@ -30,12 +35,15 @@
 def _open_stream(
     file_url: str,
     timeout: int,
+    start_byte: int = 0,
 ) -> requests.Response:
+    headers = {"Range": f"bytes={start_byte}-"} if start_byte > 0 else None
     response = requests.get(
         file_url,
         stream=True,
         timeout=timeout,
         allow_redirects=False,
+        headers=headers,
     )
     response.raise_for_status()
     return response
@@ -48,14 +56,24 @@ def download_file(
     timeout: int = _DEFAULT_TIMEOUT_SECONDS,
     max_bytes: int = _MAX_RESPONSE_BYTES,
     progress_name: str | None = None,
+    resume: bool = False,
+    expected_sha256: str | None = None,
 ) -> bool:
     """Download ``file_url`` to ``file_name`` with progress display.
 
     Validates the URL against SSRF rules, disables redirects, enforces a size
     cap, retries transient network errors up to three times, and uses default
-    TLS verification. Pass ``progress_name`` to register the transfer with
+    TLS verification.
+
+    Pass ``progress_name`` to register the transfer with
     :data:`~automation_file.core.progress.progress_registry` so it can be
-    polled or cancelled from the GUI. Returns True on success.
+    polled or cancelled from the GUI. When ``resume=True`` the download
+    streams into ``<file_name>.part`` and, if that file already exists from a
+    previous interrupted run, sends ``Range: bytes=<existing>-`` to continue
+    where it stopped (append mode); the ``.part`` file is atomically renamed
+    to ``file_name`` on success. Pass ``expected_sha256`` to verify the
+    finished file; a mismatch is logged, the download is removed, and the
+    function returns ``False``. Returns True on success.
     """
     try:
         validate_http_url(file_url)
@@ -63,8 +81,13 @@ def download_file(
         file_automation_logger.error("download_file rejected URL: %r", error)
         return False
 
+    target = Path(file_name)
+    part_path = target.with_suffix(target.suffix + ".part") if resume else target
+    start_byte = part_path.stat().st_size if resume and part_path.exists() else 0
+    write_mode = "ab" if start_byte > 0 else "wb"
+
     try:
-        response = _open_stream(file_url, timeout)
+        response = _open_stream(file_url, timeout, start_byte=start_byte)
     except RetryExhaustedException as error:
         file_automation_logger.error("download_file retries exhausted: %r", error)
         return False
@@ -75,12 +98,11 @@ def download_file(
         file_automation_logger.error("download_file request error: %r", error)
         return False
 
-    total_size = int(response.headers.get("content-length", 0))
+    remaining = int(response.headers.get("content-length", 0))
+    total_size = start_byte + remaining
     if total_size > max_bytes:
         file_automation_logger.error(
-            "download_file rejected: content-length %d > %d",
-            total_size,
-            max_bytes,
+            "download_file rejected: content-length %d > %d", total_size, max_bytes
         )
         return False
 
@@ -88,10 +110,17 @@ def download_file(
     token = None
     if progress_name:
         reporter, token = progress_registry.create(progress_name, total=total_size or None)
+        if start_byte > 0:
+            reporter.update(start_byte)
 
-    written = 0
+    written = start_byte
     try:
-        with open(file_name, "wb") as output, _progress(total_size, file_name) as progress:
+        with (
+            open(part_path, write_mode) as output,
+            _progress(total_size, str(target)) as progress,
+        ):
+            if start_byte > 0:
+                progress.update(start_byte)
             for chunk in response.iter_content(chunk_size=chunk_size):
                 if token is not None:
                     token.raise_if_cancelled()
@@ -100,8 +129,7 @@ def download_file(
                 written += len(chunk)
                 if written > max_bytes:
                     file_automation_logger.error(
-                        "download_file aborted: stream exceeded %d bytes",
-                        max_bytes,
+                        "download_file aborted: stream exceeded %d bytes", max_bytes
                     )
                     if reporter is not None:
                         reporter.finish(status="aborted")
@@ -121,9 +149,20 @@ def download_file(
             reporter.finish(status="error")
         return False
 
+    if resume and part_path != target:
+        os.replace(part_path, target)
+
+    if expected_sha256 and not verify_checksum(target, expected_sha256):
+        file_automation_logger.error("download_file checksum mismatch for %s; removing", target)
+        with contextlib.suppress(OSError):
+            target.unlink()
+        if reporter is not None:
+            reporter.finish(status="checksum_failed")
+        return False
+
     if reporter is not None:
         reporter.finish(status="done")
-    file_automation_logger.info("download_file: %s -> %s (%d bytes)", file_url, file_name, written)
+    file_automation_logger.info("download_file: %s -> %s (%d bytes)", file_url, target, written)
     return True
 
 
diff --git a/tests/test_checksum.py b/tests/test_checksum.py
new file mode 100644
index 0000000..781cfbf
--- /dev/null
+++ b/tests/test_checksum.py
@@ -0,0 +1,80 @@
+"""Tests for automation_file.core.checksum."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import pytest
+
+from automation_file.core.checksum import (
+    ChecksumMismatchException,
+    file_checksum,
+    verify_checksum,
+)
+from automation_file.exceptions import FileNotExistsException
+
+
+def _sha256(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def test_file_checksum_sha256(tmp_path: Path) -> None:
+    target = tmp_path / "hello.txt"
+    target.write_bytes(b"hello world")
+    assert file_checksum(target) == _sha256(b"hello world")
+
+
+def test_file_checksum_streams_large_file(tmp_path: Path) -> None:
+    target = tmp_path / "big.bin"
+    payload = b"\x00" * (3 * 1024 * 1024 + 17)
+    target.write_bytes(payload)
+    assert file_checksum(target, chunk_size=4096) == _sha256(payload)
+
+
+def test_file_checksum_md5(tmp_path: Path) -> None:
+    target = tmp_path / "a.bin"
+    target.write_bytes(b"hi")
+    assert file_checksum(target, algorithm="md5") == hashlib.md5(b"hi").hexdigest()
+
+
+def test_file_checksum_unknown_algorithm(tmp_path: Path) -> None:
+    target = tmp_path / "a.bin"
+    target.write_bytes(b"hi")
+    with pytest.raises(ValueError):
+        file_checksum(target, algorithm="definitely-not-a-hash")
+
+
+def test_file_checksum_missing_file(tmp_path: Path) -> None:
+    with pytest.raises(FileNotExistsException):
+        file_checksum(tmp_path / "nope")
+
+
+def test_verify_checksum_match(tmp_path: Path) -> None:
+    target = tmp_path / "hello.txt"
+    target.write_bytes(b"hello world")
+    assert verify_checksum(target, _sha256(b"hello world")) is True
+
+
+def test_verify_checksum_is_case_insensitive(tmp_path: Path) -> None:
+    target = tmp_path / "hello.txt"
+    target.write_bytes(b"hello world")
+    assert verify_checksum(target, _sha256(b"hello world").upper()) is True
+
+
+def test_verify_checksum_mismatch(tmp_path: Path) -> None:
+    target = tmp_path / "hello.txt"
+    target.write_bytes(b"hello world")
+    assert verify_checksum(target, "0" * 64) is False
+
+
+def test_checksum_mismatch_exception_exists() -> None:
+    assert issubclass(ChecksumMismatchException, Exception)
+
+
+def test_checksum_actions_registered() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    registry = build_default_registry()
+    assert "FA_file_checksum" in registry
+    assert "FA_verify_checksum" in registry
diff --git a/tests/test_http_download_resume.py b/tests/test_http_download_resume.py
new file mode 100644
index 0000000..350c55e
--- /dev/null
+++ b/tests/test_http_download_resume.py
@@ -0,0 +1,121 @@
+"""Tests for download_file resume + checksum integration."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+import pytest
+import requests
+
+from automation_file.remote import http_download
+
+
+class _FakeResponse:
+    def __init__(self, chunks: list[bytes]) -> None:
+        self._chunks = chunks
+        self.headers = {"content-length": str(sum(len(c) for c in chunks))}
+        self.status_code = 206 if chunks else 200
+
+    def raise_for_status(self) -> None: ...
+
+    def iter_content(self, chunk_size: int) -> list[bytes]:
+        return list(self._chunks)
+
+
+@pytest.fixture
+def patch_validator(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(http_download, "validate_http_url", lambda _url: None, raising=True)
+
+
+def _patch_requests(
+    monkeypatch: pytest.MonkeyPatch,
+    captured: dict[str, Any],
+    chunks: list[bytes],
+) -> None:
+    def fake_get(url: str, **kwargs: Any) -> _FakeResponse:
+        captured["url"] = url
+        captured["headers"] = kwargs.get("headers")
+        return _FakeResponse(chunks)
+
+    monkeypatch.setattr(requests, "get", fake_get, raising=True)
+
+
+def test_download_resume_sends_range_header_and_appends(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, patch_validator: None
+) -> None:
+    target = tmp_path / "big.bin"
+    part = tmp_path / "big.bin.part"
+    part.write_bytes(b"ALREADY-")  # 8 bytes pre-downloaded
+
+    captured: dict[str, Any] = {}
+    _patch_requests(monkeypatch, captured, [b"AFTER"])
+
+    ok = http_download.download_file("https://example.com/big.bin", str(target), resume=True)
+
+    assert ok is True
+    assert target.read_bytes() == b"ALREADY-AFTER"
+    assert not part.exists()  # renamed
+    assert captured["headers"] == {"Range": "bytes=8-"}
+
+
+def test_download_without_resume_skips_part_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, patch_validator: None
+) -> None:
+    target = tmp_path / "big.bin"
+    captured: dict[str, Any] = {}
+    _patch_requests(monkeypatch, captured, [b"CONTENT"])
+
+    ok = http_download.download_file("https://example.com/big.bin", str(target), resume=False)
+
+    assert ok is True
+    assert target.read_bytes() == b"CONTENT"
+    assert not (tmp_path / "big.bin.part").exists()
+    assert captured["headers"] is None
+
+
+def test_download_fresh_resume_without_existing_part(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, patch_validator: None
+) -> None:
+    target = tmp_path / "big.bin"
+    captured: dict[str, Any] = {}
+    _patch_requests(monkeypatch, captured, [b"PAYLOAD"])
+
+    ok = http_download.download_file("https://example.com/big.bin", str(target), resume=True)
+
+    assert ok is True
+    assert target.read_bytes() == b"PAYLOAD"
+    assert captured["headers"] is None  # no Range since nothing pre-downloaded
+
+
+def test_download_verifies_sha256_match(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, patch_validator: None
+) -> None:
+    payload = b"verified"
+    target = tmp_path / "v.bin"
+    captured: dict[str, Any] = {}
+    _patch_requests(monkeypatch, captured, [payload])
+
+    digest = hashlib.sha256(payload).hexdigest()
+    ok = http_download.download_file(
+        "https://example.com/v.bin", str(target), expected_sha256=digest
+    )
+
+    assert ok is True
+    assert target.exists()
+
+
+def test_download_checksum_mismatch_removes_file(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, patch_validator: None
+) -> None:
+    target = tmp_path / "v.bin"
+    captured: dict[str, Any] = {}
+    _patch_requests(monkeypatch, captured, [b"bad"])
+
+    ok = http_download.download_file(
+        "https://example.com/v.bin", str(target), expected_sha256="0" * 64
+    )
+
+    assert ok is False
+    assert not target.exists()

From 1dd4c360a7419bcd8882d1fb9ebf16f89022c921 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 20:55:10 +0800
Subject: [PATCH 08/38] Add FA_find_duplicates: size/partial-hash/full-hash
 dedup pipeline

---
 automation_file/__init__.py             |   2 +
 automation_file/core/action_registry.py |   3 +-
 automation_file/utils/deduplicate.py    | 126 ++++++++++++++++++++++++
 tests/test_deduplicate.py               | 107 ++++++++++++++++++++
 4 files changed, 237 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/utils/deduplicate.py
 create mode 100644 tests/test_deduplicate.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 32872cb..99abf53 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -124,6 +124,7 @@
     watch_stop,
     watch_stop_all,
 )
+from automation_file.utils.deduplicate import find_duplicates
 from automation_file.utils.fast_find import fast_find, has_os_index, scandir_find
 from automation_file.utils.file_discovery import get_dir_files_as_list
 
@@ -230,6 +231,7 @@ def __getattr__(name: str) -> Any:
     "file_checksum",
     "verify_checksum",
     "ChecksumMismatchException",
+    "find_duplicates",
     # Triggers
     "FileWatcher",
     "TriggerManager",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index d0c2386..4f71beb 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -131,12 +131,13 @@ def _http_commands() -> dict[str, Command]:
 
 def _utils_commands() -> dict[str, Command]:
     from automation_file.core import checksum
-    from automation_file.utils import fast_find
+    from automation_file.utils import deduplicate, fast_find
 
     return {
         "FA_fast_find": fast_find.fast_find,
         "FA_file_checksum": checksum.file_checksum,
         "FA_verify_checksum": checksum.verify_checksum,
+        "FA_find_duplicates": deduplicate.find_duplicates,
     }
 
 
diff --git a/automation_file/utils/deduplicate.py b/automation_file/utils/deduplicate.py
new file mode 100644
index 0000000..7808ac3
--- /dev/null
+++ b/automation_file/utils/deduplicate.py
@@ -0,0 +1,126 @@
+"""Find duplicate files with a three-stage size-then-hash pipeline.
+
+Brute-force content hashing every file in a tree is wasteful: most files
+have a unique size and can be ruled out instantly. This module runs three
+cheap-to-expensive stages:
+
+1. **Group by size** — one ``stat()`` per file; unique sizes are skipped.
+2. **Partial hash** — hash the first ``sample_bytes`` of each size collision.
+3. **Full hash** — only for paths whose partial hash matches another.
+
+The result is a list of duplicate groups, where each group is a list of
+absolute paths that share the same content.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from collections import defaultdict
+from pathlib import Path
+
+from automation_file.logging_config import file_automation_logger
+
+__all__ = ["find_duplicates"]
+
+_DEFAULT_SAMPLE_BYTES = 64 * 1024
+_DEFAULT_ALGO = "sha256"
+
+
+def find_duplicates(
+    root: str | os.PathLike[str],
+    *,
+    min_size: int = 1,
+    sample_bytes: int = _DEFAULT_SAMPLE_BYTES,
+    algorithm: str = _DEFAULT_ALGO,
+) -> list[list[str]]:
+    """Return duplicate groups under ``root``.
+
+    ``min_size`` skips zero-byte or tiny files (default 1 — so empty files
+    are excluded). ``sample_bytes`` controls the partial-hash window; a
+    larger sample catches more mismatches on stage two at the cost of more
+    I/O. ``algorithm`` is any name :func:`hashlib.new` understands.
+
+    Groups are returned sorted by size descending, then each group's paths
+    are sorted for stable output.
+    """
+    root_path = Path(root).expanduser().resolve()
+    if not root_path.is_dir():
+        return []
+
+    by_size = _group_by_size(root_path, min_size)
+    by_partial = _refine(by_size, lambda p: _hash_head(p, sample_bytes, algorithm))
+    by_full = _refine(by_partial, lambda p: _hash_full(p, algorithm))
+
+    groups = [sorted(paths) for paths in by_full.values() if len(paths) > 1]
+    groups.sort(key=lambda g: (-_safe_size(g[0]), g[0]))
+    return groups
+
+
+def _group_by_size(root: Path, min_size: int) -> dict[int, list[str]]:
+    buckets: dict[int, list[str]] = defaultdict(list)
+    stack: list[str] = [str(root)]
+    while stack:
+        current = stack.pop()
+        try:
+            iterator = os.scandir(current)
+        except (PermissionError, FileNotFoundError, OSError):
+            continue
+        with iterator as entries:
+            for entry in entries:
+                try:
+                    if entry.is_dir(follow_symlinks=False):
+                        stack.append(entry.path)
+                        continue
+                    if not entry.is_file(follow_symlinks=False):
+                        continue
+                    size = entry.stat(follow_symlinks=False).st_size
+                except OSError:
+                    continue
+                if size < min_size:
+                    continue
+                buckets[size].append(os.path.abspath(entry.path))
+    return {size: paths for size, paths in buckets.items() if len(paths) > 1}
+
+
+def _refine(groups: dict, hash_fn) -> dict[tuple, list[str]]:
+    refined: dict[tuple, list[str]] = defaultdict(list)
+    for key, paths in groups.items():
+        if len(paths) < 2:
+            continue
+        for path in paths:
+            digest = hash_fn(path)
+            if digest is None:
+                continue
+            refined[(key, digest)].append(path)
+    return {k: v for k, v in refined.items() if len(v) > 1}
+
+
+def _hash_head(path: str, sample_bytes: int, algorithm: str) -> str | None:
+    try:
+        digest = hashlib.new(algorithm)
+        with open(path, "rb") as handle:
+            digest.update(handle.read(sample_bytes))
+    except OSError as err:
+        file_automation_logger.debug("dedup head-hash skipped %s: %r", path, err)
+        return None
+    return digest.hexdigest()
+
+
+def _hash_full(path: str, algorithm: str) -> str | None:
+    try:
+        digest = hashlib.new(algorithm)
+        with open(path, "rb") as handle:
+            for block in iter(lambda: handle.read(1024 * 1024), b""):
+                digest.update(block)
+    except OSError as err:
+        file_automation_logger.debug("dedup full-hash skipped %s: %r", path, err)
+        return None
+    return digest.hexdigest()
+
+
+def _safe_size(path: str) -> int:
+    try:
+        return os.path.getsize(path)
+    except OSError:
+        return 0
diff --git a/tests/test_deduplicate.py b/tests/test_deduplicate.py
new file mode 100644
index 0000000..3bf80f2
--- /dev/null
+++ b/tests/test_deduplicate.py
@@ -0,0 +1,107 @@
+"""Tests for automation_file.utils.deduplicate."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from automation_file.utils.deduplicate import find_duplicates
+
+
+def _write(path: Path, payload: bytes) -> None:
+    path.write_bytes(payload)
+
+
+def test_finds_simple_duplicates(tmp_path: Path) -> None:
+    _write(tmp_path / "a.bin", b"same-content")
+    _write(tmp_path / "b.bin", b"same-content")
+    _write(tmp_path / "c.bin", b"unique")
+
+    groups = find_duplicates(tmp_path)
+    assert len(groups) == 1
+    names = sorted(Path(p).name for p in groups[0])
+    assert names == ["a.bin", "b.bin"]
+
+
+def test_ignores_unique_sizes(tmp_path: Path) -> None:
+    _write(tmp_path / "a.bin", b"x")
+    _write(tmp_path / "b.bin", b"yy")
+    _write(tmp_path / "c.bin", b"zzz")
+    assert find_duplicates(tmp_path) == []
+
+
+def test_same_size_different_content_not_grouped(tmp_path: Path) -> None:
+    _write(tmp_path / "a.bin", b"aaaaaaaa")
+    _write(tmp_path / "b.bin", b"bbbbbbbb")
+    assert find_duplicates(tmp_path) == []
+
+
+def test_nested_tree(tmp_path: Path) -> None:
+    sub = tmp_path / "sub"
+    sub.mkdir()
+    _write(tmp_path / "a.bin", b"dup")
+    _write(sub / "b.bin", b"dup")
+    groups = find_duplicates(tmp_path)
+    assert len(groups) == 1
+    assert len(groups[0]) == 2
+
+
+def test_three_way_duplicate(tmp_path: Path) -> None:
+    payload = b"triple-match"
+    _write(tmp_path / "a", payload)
+    _write(tmp_path / "b", payload)
+    _write(tmp_path / "c", payload)
+    groups = find_duplicates(tmp_path)
+    assert len(groups) == 1
+    assert len(groups[0]) == 3
+
+
+def test_min_size_skips_small_files(tmp_path: Path) -> None:
+    _write(tmp_path / "a.bin", b"ab")
+    _write(tmp_path / "b.bin", b"ab")
+    assert find_duplicates(tmp_path, min_size=10) == []
+
+
+def test_partial_hash_rules_out_with_matching_size(tmp_path: Path) -> None:
+    # Same size, different content across the whole file, different first bytes
+    size = 200_000
+    a = b"A" * size
+    b = b"B" * size
+    _write(tmp_path / "a.bin", a)
+    _write(tmp_path / "b.bin", b)
+    assert find_duplicates(tmp_path, sample_bytes=16) == []
+
+
+def test_full_hash_needed_when_prefix_matches(tmp_path: Path) -> None:
+    prefix = b"X" * 64
+    _write(tmp_path / "a.bin", prefix + b"tail-a")
+    _write(tmp_path / "b.bin", prefix + b"tail-b")
+    assert find_duplicates(tmp_path, sample_bytes=64) == []
+
+
+def test_returns_groups_largest_first(tmp_path: Path) -> None:
+    big = b"X" * 1024
+    small = b"Y" * 32
+    _write(tmp_path / "big-1.bin", big)
+    _write(tmp_path / "big-2.bin", big)
+    _write(tmp_path / "small-1.bin", small)
+    _write(tmp_path / "small-2.bin", small)
+    groups = find_duplicates(tmp_path)
+    assert len(groups) == 2
+    assert Path(groups[0][0]).name.startswith("big")
+
+
+def test_returns_absolute_paths(tmp_path: Path) -> None:
+    _write(tmp_path / "a.bin", b"dup")
+    _write(tmp_path / "b.bin", b"dup")
+    groups = find_duplicates(tmp_path)
+    assert all(Path(p).is_absolute() for group in groups for p in group)
+
+
+def test_missing_root_returns_empty(tmp_path: Path) -> None:
+    assert find_duplicates(tmp_path / "nope") == []
+
+
+def test_find_duplicates_registered_in_registry() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    assert "FA_find_duplicates" in build_default_registry()

From 8f6ecfaf250046242698463c7caea93ab2c93084 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 21:01:22 +0800
Subject: [PATCH 09/38] Add execute_action_dag: topological action scheduler

Runs nodes in dependency order with a shared thread pool, parallelising
independent branches. Validates cycles, unknown deps, self-deps, and
duplicate ids up-front. On node failure, transitive dependents are
marked skipped (fail_fast=True) or still run (fail_fast=False).
---
 automation_file/__init__.py             |   2 +
 automation_file/core/action_registry.py |  12 ++
 automation_file/core/dag_executor.py    | 175 ++++++++++++++++++++++++
 automation_file/exceptions.py           |   4 +
 tests/test_dag_executor.py              | 167 ++++++++++++++++++++++
 5 files changed, 360 insertions(+)
 create mode 100644 automation_file/core/dag_executor.py
 create mode 100644 tests/test_dag_executor.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 99abf53..be20fb0 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -25,6 +25,7 @@
     file_checksum,
     verify_checksum,
 )
+from automation_file.core.dag_executor import execute_action_dag
 from automation_file.core.json_store import read_action_json, write_action_json
 from automation_file.core.package_loader import PackageLoader
 from automation_file.core.progress import (
@@ -156,6 +157,7 @@ def __getattr__(name: str) -> Any:
     "build_default_registry",
     "execute_action",
     "execute_action_parallel",
+    "execute_action_dag",
     "execute_files",
     "validate_action",
     "retry_on_transient",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 4f71beb..64ab22b 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -138,9 +138,21 @@ def _utils_commands() -> dict[str, Command]:
         "FA_file_checksum": checksum.file_checksum,
         "FA_verify_checksum": checksum.verify_checksum,
         "FA_find_duplicates": deduplicate.find_duplicates,
+        "FA_execute_action_dag": _lazy_execute_action_dag,
     }
 
 
+def _lazy_execute_action_dag(
+    nodes: list,
+    max_workers: int = 4,
+    fail_fast: bool = True,
+) -> dict[str, Any]:
+    """Deferred import shim so the registry module doesn't depend on the DAG executor."""
+    from automation_file.core.dag_executor import execute_action_dag
+
+    return execute_action_dag(nodes, max_workers=max_workers, fail_fast=fail_fast)
+
+
 def _register_cloud_backends(registry: ActionRegistry) -> None:
     from automation_file.remote.azure_blob import register_azure_blob_ops
     from automation_file.remote.dropbox_api import register_dropbox_ops
diff --git a/automation_file/core/dag_executor.py b/automation_file/core/dag_executor.py
new file mode 100644
index 0000000..7bea7d3
--- /dev/null
+++ b/automation_file/core/dag_executor.py
@@ -0,0 +1,175 @@
+"""DAG executor — run actions in dependency order, parallelising independent branches.
+
+A DAG node is a dict:
+
+.. code-block:: python
+
+   {"id": "build", "action": ["FA_create_dir", {"dir_path": "build"}]}
+   {"id": "zip", "action": ["FA_zip_dir", ...], "depends_on": ["build"]}
+
+The executor performs Kahn-style topological scheduling: every node whose
+dependencies are satisfied becomes runnable and is dispatched to a shared
+thread pool immediately — so diamonds and wide fan-outs run in parallel
+without the caller hand-tuning ``max_workers`` around dependency edges.
+
+If a node raises, its transitive dependents are marked ``skipped`` by
+default (fail-fast semantics). Pass ``fail_fast=False`` to run dependents
+regardless (useful for cleanup steps).
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import defaultdict, deque
+from collections.abc import Mapping
+from concurrent.futures import FIRST_COMPLETED, Future, ThreadPoolExecutor, wait
+from typing import Any
+
+from automation_file.core.action_executor import executor as default_executor
+from automation_file.exceptions import DagException
+
+__all__ = ["execute_action_dag"]
+
+
+def execute_action_dag(
+    nodes: list[Mapping[str, Any]],
+    max_workers: int = 4,
+    fail_fast: bool = True,
+) -> dict[str, Any]:
+    """Run ``nodes`` in topological order, parallelising independent branches.
+
+    Each node is ``{"id": str, "action": [...], "depends_on": [id, ...]}``.
+    ``depends_on`` is optional (default ``[]``). Returns a dict mapping each
+    node id to either the action's return value, the repr of its exception,
+    or ``"skipped: <reason>"`` when ``fail_fast`` blocks a branch.
+
+    Raises :class:`DagException` for static errors detected before any action
+    runs: duplicate ids, unknown dependencies, or cycles.
+    """
+    graph, indegree = _build_graph(nodes)
+    node_map = {_require_id(node): node for node in nodes}
+    results: dict[str, Any] = {}
+    lock = threading.Lock()
+
+    ready: deque[str] = deque(node_id for node_id, count in indegree.items() if count == 0)
+
+    with ThreadPoolExecutor(max_workers=max_workers) as pool:
+        in_flight: dict[Future[Any], str] = {}
+
+        def submit(node_id: str) -> None:
+            action = node_map[node_id].get("action")
+            if not isinstance(action, list):
+                err = DagException(f"node {node_id!r} missing action list")
+                with lock:
+                    results[node_id] = repr(err)
+                if fail_fast:
+                    for dependent in graph.get(node_id, ()):
+                        indegree[dependent] -= 1
+                        _mark_skipped(dependent, node_id, graph, indegree, results, lock)
+                return
+            future = pool.submit(_run_action, action)
+            in_flight[future] = node_id
+
+        while ready or in_flight:
+            while ready:
+                submit(ready.popleft())
+            if not in_flight:
+                break
+            done, _ = wait(list(in_flight), return_when=FIRST_COMPLETED)
+            for future in done:
+                node_id = in_flight.pop(future)
+                failed = False
+                try:
+                    value: Any = future.result()
+                except Exception as err:  # pylint: disable=broad-except
+                    value = repr(err)
+                    failed = True
+                with lock:
+                    results[node_id] = value
+                for dependent in graph.get(node_id, ()):
+                    indegree[dependent] -= 1
+                    if failed and fail_fast:
+                        _mark_skipped(dependent, node_id, graph, indegree, results, lock)
+                    elif indegree[dependent] == 0 and dependent not in results:
+                        ready.append(dependent)
+
+    return results
+
+
+def _run_action(action: list) -> Any:
+    # Use the single-action path so exceptions surface as real exceptions
+    # rather than being swallowed by execute_action's per-action try/except.
+    return default_executor._execute_event(action)
+
+
+def _build_graph(
+    nodes: list[Mapping[str, Any]],
+) -> tuple[dict[str, list[str]], dict[str, int]]:
+    graph: dict[str, list[str]] = defaultdict(list)
+    indegree: dict[str, int] = {}
+    ids: set[str] = set()
+
+    for node in nodes:
+        node_id = _require_id(node)
+        if node_id in ids:
+            raise DagException(f"duplicate node id: {node_id!r}")
+        ids.add(node_id)
+        indegree[node_id] = 0
+
+    for node in nodes:
+        node_id = _require_id(node)
+        deps = node.get("depends_on", []) or []
+        if not isinstance(deps, list):
+            raise DagException(f"node {node_id!r} depends_on must be list")
+        for dep in deps:
+            if dep not in ids:
+                raise DagException(f"node {node_id!r} depends on unknown id {dep!r}")
+            if dep == node_id:
+                raise DagException(f"node {node_id!r} depends on itself")
+            graph[dep].append(node_id)
+            indegree[node_id] += 1
+
+    _detect_cycle(ids, graph, dict(indegree))
+    return dict(graph), indegree
+
+
+def _require_id(node: Mapping[str, Any]) -> str:
+    node_id = node.get("id")
+    if not isinstance(node_id, str) or not node_id:
+        raise DagException(f"node missing non-empty 'id': {node!r}")
+    return node_id
+
+
+def _detect_cycle(
+    ids: set[str],
+    graph: dict[str, list[str]],
+    indegree: dict[str, int],
+) -> None:
+    queue: deque[str] = deque(node_id for node_id, count in indegree.items() if count == 0)
+    visited = 0
+    while queue:
+        current = queue.popleft()
+        visited += 1
+        for dependent in graph.get(current, ()):
+            indegree[dependent] -= 1
+            if indegree[dependent] == 0:
+                queue.append(dependent)
+    if visited != len(ids):
+        raise DagException("cycle detected in DAG")
+
+
+def _mark_skipped(
+    dependent: str,
+    reason_id: str,
+    graph: dict[str, list[str]],
+    indegree: dict[str, int],
+    results: dict[str, Any],
+    lock: threading.Lock,
+) -> None:
+    with lock:
+        if dependent in results:
+            return
+        results[dependent] = f"skipped: dep {reason_id!r} failed"
+    for grandchild in graph.get(dependent, ()):
+        indegree[grandchild] -= 1
+        _mark_skipped(grandchild, dependent, graph, indegree, results, lock)
diff --git a/automation_file/exceptions.py b/automation_file/exceptions.py
index 7908413..8bdecdc 100644
--- a/automation_file/exceptions.py
+++ b/automation_file/exceptions.py
@@ -67,6 +67,10 @@ class TCPAuthException(FileAutomationException):
     """Raised when a TCP client fails shared-secret authentication."""
 
 
+class DagException(FileAutomationException):
+    """Raised when a DAG action list has a cycle, unknown dep, or duplicate id."""
+
+
 _ARGPARSE_EMPTY_MESSAGE = "argparse received no actionable argument"
 _BAD_TRIGGER_FUNCTION = "trigger name is not registered in the executor"
 _BAD_CALLBACK_METHOD = "callback_param_method must be 'kwargs' or 'args'"
diff --git a/tests/test_dag_executor.py b/tests/test_dag_executor.py
new file mode 100644
index 0000000..618025b
--- /dev/null
+++ b/tests/test_dag_executor.py
@@ -0,0 +1,167 @@
+"""Tests for automation_file.core.dag_executor."""
+
+from __future__ import annotations
+
+import threading
+import time
+
+import pytest
+
+from automation_file import add_command_to_executor, execute_action_dag
+from automation_file.exceptions import DagException
+
+
+@pytest.fixture(autouse=True)
+def _register_test_commands() -> None:
+    calls: list[str] = []
+    lock = threading.Lock()
+
+    def record(name: str, delay: float = 0.0) -> str:
+        if delay:
+            time.sleep(delay)
+        with lock:
+            calls.append(name)
+        return name
+
+    def boom() -> None:
+        raise RuntimeError("planned-failure")
+
+    add_command_to_executor(
+        {
+            "_dag_record": record,
+            "_dag_boom": boom,
+        }
+    )
+
+
+def test_linear_chain_runs_in_order() -> None:
+    results = execute_action_dag(
+        [
+            {"id": "a", "action": ["_dag_record", ["a"]]},
+            {"id": "b", "action": ["_dag_record", ["b"]], "depends_on": ["a"]},
+            {"id": "c", "action": ["_dag_record", ["c"]], "depends_on": ["b"]},
+        ]
+    )
+    assert results == {"a": "a", "b": "b", "c": "c"}
+
+
+def test_diamond_converges() -> None:
+    results = execute_action_dag(
+        [
+            {"id": "top", "action": ["_dag_record", ["top"]]},
+            {"id": "left", "action": ["_dag_record", ["left"]], "depends_on": ["top"]},
+            {"id": "right", "action": ["_dag_record", ["right"]], "depends_on": ["top"]},
+            {
+                "id": "bottom",
+                "action": ["_dag_record", ["bottom"]],
+                "depends_on": ["left", "right"],
+            },
+        ]
+    )
+    assert results["top"] == "top"
+    assert results["left"] == "left"
+    assert results["right"] == "right"
+    assert results["bottom"] == "bottom"
+
+
+def test_independent_branches_parallelise() -> None:
+    start = time.monotonic()
+    execute_action_dag(
+        [
+            {"id": "a", "action": ["_dag_record", ["a", 0.3]]},
+            {"id": "b", "action": ["_dag_record", ["b", 0.3]]},
+            {"id": "c", "action": ["_dag_record", ["c", 0.3]]},
+        ],
+        max_workers=3,
+    )
+    elapsed = time.monotonic() - start
+    assert elapsed < 0.8, f"independent branches should parallelise, took {elapsed:.2f}s"
+
+
+def test_failure_skips_dependents_by_default() -> None:
+    results = execute_action_dag(
+        [
+            {"id": "root", "action": ["_dag_boom"]},
+            {"id": "child", "action": ["_dag_record", ["child"]], "depends_on": ["root"]},
+            {
+                "id": "grand",
+                "action": ["_dag_record", ["grand"]],
+                "depends_on": ["child"],
+            },
+        ]
+    )
+    assert "RuntimeError" in results["root"]
+    assert results["child"].startswith("skipped: dep 'root' failed")
+    assert results["grand"].startswith("skipped: dep 'child' failed")
+
+
+def test_fail_fast_false_still_runs_dependents() -> None:
+    results = execute_action_dag(
+        [
+            {"id": "root", "action": ["_dag_boom"]},
+            {"id": "child", "action": ["_dag_record", ["child"]], "depends_on": ["root"]},
+        ],
+        fail_fast=False,
+    )
+    assert "RuntimeError" in results["root"]
+    assert results["child"] == "child"
+
+
+def test_cycle_detected() -> None:
+    with pytest.raises(DagException, match="cycle"):
+        execute_action_dag(
+            [
+                {"id": "a", "action": ["_dag_record", ["a"]], "depends_on": ["b"]},
+                {"id": "b", "action": ["_dag_record", ["b"]], "depends_on": ["a"]},
+            ]
+        )
+
+
+def test_unknown_dep_rejected() -> None:
+    with pytest.raises(DagException, match="unknown id"):
+        execute_action_dag(
+            [
+                {"id": "a", "action": ["_dag_record", ["a"]], "depends_on": ["missing"]},
+            ]
+        )
+
+
+def test_duplicate_id_rejected() -> None:
+    with pytest.raises(DagException, match="duplicate"):
+        execute_action_dag(
+            [
+                {"id": "dup", "action": ["_dag_record", ["a"]]},
+                {"id": "dup", "action": ["_dag_record", ["b"]]},
+            ]
+        )
+
+
+def test_self_dependency_rejected() -> None:
+    with pytest.raises(DagException, match="itself"):
+        execute_action_dag(
+            [
+                {"id": "a", "action": ["_dag_record", ["a"]], "depends_on": ["a"]},
+            ]
+        )
+
+
+def test_missing_id_rejected() -> None:
+    with pytest.raises(DagException, match="non-empty 'id'"):
+        execute_action_dag([{"action": ["_dag_record", ["a"]]}])
+
+
+def test_node_missing_action_list() -> None:
+    results = execute_action_dag(
+        [
+            {"id": "bad"},
+            {"id": "child", "action": ["_dag_record", ["child"]], "depends_on": ["bad"]},
+        ]
+    )
+    assert "missing action list" in results["bad"]
+    assert results["child"].startswith("skipped")
+
+
+def test_dag_action_registered_in_default_registry() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    assert "FA_execute_action_dag" in build_default_registry()

From fdc2fa481ec65d94e09e3a803fe2eb2f9ada024a Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 21:03:30 +0800
Subject: [PATCH 10/38] Add entry-point plugin discovery

Third-party packages advertising 'automation_file.actions' entry points
are loaded by build_default_registry() so their commands land in every
freshly-built registry. Each plugin entry point resolves to a
zero-argument factory returning a {name: callable} mapping.

Plugin failures (load, factory, bad return shape, registry rejection)
are logged and swallowed so one broken plugin cannot break the library
for other callers.
---
 automation_file/core/action_registry.py |  14 ++-
 automation_file/core/plugins.py         |  86 ++++++++++++++++
 tests/test_plugins.py                   | 128 ++++++++++++++++++++++++
 3 files changed, 227 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/core/plugins.py
 create mode 100644 tests/test_plugins.py

diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 64ab22b..bf1238f 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -184,7 +184,12 @@ def _register_progress_ops(registry: ActionRegistry) -> None:
 
 
 def build_default_registry() -> ActionRegistry:
-    """Return a registry pre-populated with every built-in ``FA_*`` action."""
+    """Return a registry pre-populated with every built-in ``FA_*`` action.
+
+    After the built-ins are registered, any third-party package advertising
+    an ``automation_file.actions`` entry point is loaded so its commands
+    land in the same registry. Plugins may override built-in names.
+    """
     registry = ActionRegistry()
     registry.register_many(_local_commands())
     registry.register_many(_http_commands())
@@ -194,7 +199,14 @@ def build_default_registry() -> ActionRegistry:
     _register_trigger_ops(registry)
     _register_scheduler_ops(registry)
     _register_progress_ops(registry)
+    _load_plugins(registry)
     file_automation_logger.info(
         "action_registry: built default registry with %d commands", len(registry)
     )
     return registry
+
+
+def _load_plugins(registry: ActionRegistry) -> None:
+    from automation_file.core.plugins import load_entry_point_plugins
+
+    load_entry_point_plugins(registry.register_many)
diff --git a/automation_file/core/plugins.py b/automation_file/core/plugins.py
new file mode 100644
index 0000000..297d2d2
--- /dev/null
+++ b/automation_file/core/plugins.py
@@ -0,0 +1,86 @@
+"""Entry-point plugin discovery.
+
+Third-party packages can register additional actions with
+``automation_file`` without the library having to import them directly.
+
+A plugin advertises itself in its ``pyproject.toml``::
+
+    [project.entry-points."automation_file.actions"]
+    my_plugin = "my_plugin:register"
+
+where ``register`` is a zero-argument callable returning a
+``Mapping[str, Callable]`` — the same shape you would pass to
+:func:`automation_file.add_command_to_executor`.
+
+:func:`load_entry_point_plugins` is invoked by
+:func:`automation_file.core.action_registry.build_default_registry` so
+installed plugins populate every freshly-built registry automatically.
+Plugin failures are logged and swallowed — one broken plugin must not
+break the library for everyone else.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from importlib.metadata import EntryPoint, entry_points
+from typing import Any
+
+from automation_file.logging_config import file_automation_logger
+
+__all__ = ["ENTRY_POINT_GROUP", "load_entry_point_plugins"]
+
+ENTRY_POINT_GROUP = "automation_file.actions"
+
+
+def load_entry_point_plugins(
+    register: Callable[[Mapping[str, Callable[..., Any]]], None],
+) -> int:
+    """Discover and register every ``automation_file.actions`` entry point.
+
+    ``register`` receives one ``{name: callable}`` mapping per plugin and
+    is responsible for storing it (typically
+    :meth:`ActionRegistry.register_many`). Returns the number of plugins
+    that registered successfully.
+    """
+    loaded = 0
+    for entry in _iter_entry_points():
+        try:
+            factory = entry.load()
+        except Exception as err:  # pylint: disable=broad-except
+            file_automation_logger.error(
+                "plugin load failed: %s (%s): %r", entry.name, entry.value, err
+            )
+            continue
+        try:
+            mapping = factory()
+        except Exception as err:  # pylint: disable=broad-except
+            file_automation_logger.error(
+                "plugin factory raised: %s (%s): %r", entry.name, entry.value, err
+            )
+            continue
+        if not isinstance(mapping, Mapping):
+            file_automation_logger.error(
+                "plugin %s returned %s, expected Mapping",
+                entry.name,
+                type(mapping).__name__,
+            )
+            continue
+        try:
+            register(mapping)
+        except Exception as err:  # pylint: disable=broad-except
+            file_automation_logger.error("plugin register failed: %s: %r", entry.name, err)
+            continue
+        file_automation_logger.info(
+            "plugin registered: %s -> %d commands", entry.name, len(mapping)
+        )
+        loaded += 1
+    return loaded
+
+
+def _iter_entry_points() -> list[EntryPoint]:
+    try:
+        return list(entry_points(group=ENTRY_POINT_GROUP))
+    except TypeError:
+        # importlib.metadata before 3.10 used a different API; the project
+        # targets 3.10+, so this branch exists only as defensive padding.
+        return list(entry_points().get(ENTRY_POINT_GROUP, []))
diff --git a/tests/test_plugins.py b/tests/test_plugins.py
new file mode 100644
index 0000000..32d2328
--- /dev/null
+++ b/tests/test_plugins.py
@@ -0,0 +1,128 @@
+"""Tests for automation_file.core.plugins (entry-point discovery)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+from unittest.mock import patch
+
+from automation_file.core.plugins import ENTRY_POINT_GROUP, load_entry_point_plugins
+
+
+class _FakeEntryPoint:
+    def __init__(self, name: str, factory: Callable[[], Any]) -> None:
+        self.name = name
+        self.value = f"fake:{name}"
+        self._factory = factory
+
+    def load(self) -> Callable[[], Any]:
+        return self._factory
+
+
+def _patch_entry_points(points: list[_FakeEntryPoint]) -> Any:
+    def fake_entry_points(*, group: str) -> list[_FakeEntryPoint]:
+        assert group == ENTRY_POINT_GROUP
+        return points
+
+    return patch("automation_file.core.plugins.entry_points", fake_entry_points)
+
+
+def test_plugin_registers_its_commands() -> None:
+    def my_action() -> str:
+        return "ok"
+
+    def factory() -> dict[str, Callable[..., Any]]:
+        return {"my_action": my_action}
+
+    registered: dict[str, Callable[..., Any]] = {}
+    with _patch_entry_points([_FakeEntryPoint("demo", factory)]):
+        count = load_entry_point_plugins(registered.update)
+
+    assert count == 1
+    assert registered["my_action"] is my_action
+
+
+def test_plugin_load_failure_is_swallowed() -> None:
+    ep = _FakeEntryPoint("broken", lambda: {})
+
+    def bad_load() -> Any:
+        raise ImportError("no module foo")
+
+    ep.load = bad_load  # type: ignore[method-assign]
+
+    with _patch_entry_points([ep]):
+        count = load_entry_point_plugins(lambda _mapping: None)
+
+    assert count == 0
+
+
+def test_plugin_factory_raising_is_swallowed() -> None:
+    def factory() -> dict[str, Callable[..., Any]]:
+        raise RuntimeError("boom")
+
+    with _patch_entry_points([_FakeEntryPoint("demo", factory)]):
+        count = load_entry_point_plugins(lambda _mapping: None)
+
+    assert count == 0
+
+
+def test_plugin_returning_non_mapping_rejected() -> None:
+    def factory() -> list[str]:
+        return ["not", "a", "mapping"]
+
+    with _patch_entry_points([_FakeEntryPoint("demo", factory)]):
+        count = load_entry_point_plugins(lambda _mapping: None)
+
+    assert count == 0
+
+
+def test_one_broken_plugin_does_not_block_others() -> None:
+    def good() -> str:
+        return "good"
+
+    def bad_factory() -> Any:
+        raise RuntimeError("nope")
+
+    def good_factory() -> dict[str, Callable[..., Any]]:
+        return {"good_action": good}
+
+    registered: dict[str, Callable[..., Any]] = {}
+    with _patch_entry_points(
+        [
+            _FakeEntryPoint("bad", bad_factory),
+            _FakeEntryPoint("good", good_factory),
+        ]
+    ):
+        count = load_entry_point_plugins(registered.update)
+
+    assert count == 1
+    assert "good_action" in registered
+
+
+def test_plugin_register_error_is_swallowed() -> None:
+    def factory() -> dict[str, Callable[..., Any]]:
+        return {"x": lambda: None}
+
+    def register(_mapping: Mapping[str, Callable[..., Any]]) -> None:
+        raise ValueError("registry rejects me")
+
+    with _patch_entry_points([_FakeEntryPoint("demo", factory)]):
+        count = load_entry_point_plugins(register)
+
+    assert count == 0
+
+
+def test_plugins_loaded_by_build_default_registry() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    def plugin_cmd() -> str:
+        return "plugged"
+
+    def factory() -> dict[str, Callable[..., Any]]:
+        return {"FA_plugin_demo": plugin_cmd}
+
+    with _patch_entry_points([_FakeEntryPoint("demo", factory)]):
+        registry = build_default_registry()
+
+    assert "FA_plugin_demo" in registry
+    assert registry.resolve("FA_plugin_demo") is plugin_cmd

From 8a15e2455a3ac9e52f9f1ed895b8c2c094f6b0b9 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 21:07:32 +0800
Subject: [PATCH 11/38] Document checksums, resume, dedup, DAG, and plugins

Add usage sections and architecture/API references for file_checksum /
verify_checksum, resumable HTTP downloads, find_duplicates,
execute_action_dag, and entry-point plugin discovery. All three language
READMEs carry the same feature bullets and examples.
---
 README.md                    | 102 ++++++++++++++++++++++++++++++
 README.zh-CN.md              |  97 ++++++++++++++++++++++++++++
 README.zh-TW.md              |  97 ++++++++++++++++++++++++++++
 docs/source/api/core.rst     |   9 +++
 docs/source/api/utils.rst    |   3 +
 docs/source/architecture.rst |  51 ++++++++++++++-
 docs/source/usage.rst        | 119 +++++++++++++++++++++++++++++++++++
 7 files changed, 476 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 9087906..c1553d3 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,11 @@ facade.
 - **Cron scheduler** — recurring action lists on a stdlib-only 5-field parser (`FA_schedule_*`)
 - **Transfer progress + cancellation** — opt-in `progress_name` hook on HTTP and S3 transfers (`FA_progress_*`)
 - **Fast file search** — OS index fast path (`mdfind` / `locate` / `es.exe`) with a streaming `scandir` fallback (`FA_fast_find`)
+- **Checksums + integrity verification** — streaming `file_checksum` / `verify_checksum` with any `hashlib` algorithm; `download_file(expected_sha256=...)` verifies after transfer (`FA_file_checksum`, `FA_verify_checksum`)
+- **Resumable HTTP downloads** — `download_file(resume=True)` writes to `<target>.part` and sends `Range: bytes=<n>-` so interrupted transfers continue
+- **Duplicate-file finder** — three-stage size → partial-hash → full-hash pipeline; unique-size files are never hashed (`FA_find_duplicates`)
+- **DAG action executor** — topological scheduling with parallel fan-out and per-branch skip-on-failure (`FA_execute_action_dag`)
+- **Entry-point plugins** — third-party packages register their own `FA_*` actions via `[project.entry-points."automation_file.actions"]`; `build_default_registry()` picks them up automatically
 - PySide6 GUI (`python -m automation_file ui`) with a tab per backend, the JSON-action runner, and dedicated tabs for Triggers, Scheduler, and live Progress
 - Rich CLI with one-shot subcommands plus legacy JSON-batch flags
 - Project scaffolding (`ProjectBuilder`) for executor-based automations
@@ -343,6 +348,103 @@ for path in scandir_find("/data", "*.csv"):
 [["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
 ```
 
+### Checksums + integrity verification
+Stream any `hashlib` algorithm; `verify_checksum` compares with
+`hmac.compare_digest` (constant-time):
+
+```python
+from automation_file import file_checksum, verify_checksum
+
+digest = file_checksum("bundle.tar.gz")                # sha256 by default
+verify_checksum("bundle.tar.gz", digest)               # -> True
+verify_checksum("bundle.tar.gz", "deadbeef...", algorithm="blake2b")
+```
+
+Also available as `FA_file_checksum` / `FA_verify_checksum` JSON actions.
+
+### Resumable HTTP downloads
+`download_file(resume=True)` writes to `<target>.part` and sends
+`Range: bytes=<n>-` on the next attempt. Pair with `expected_sha256=` for
+integrity verification once the transfer completes:
+
+```python
+from automation_file import download_file
+
+download_file(
+    "https://example.com/big.bin",
+    "big.bin",
+    resume=True,
+    expected_sha256="3b0c44298fc1...",
+)
+```
+
+### Duplicate-file finder
+Three-stage pipeline: size bucket → 64 KiB partial hash → full hash.
+Unique-size files are never hashed:
+
+```python
+from automation_file import find_duplicates
+
+groups = find_duplicates("/data", min_size=1024)
+# list[list[str]] — each inner list is a set of identical files, sorted
+# by size descending.
+```
+
+`FA_find_duplicates` runs the same search from JSON.
+
+### DAG action executor
+Run actions in dependency order; independent branches fan out across a
+thread pool. Each node is `{"id": ..., "action": [...], "depends_on":
+[...]}`:
+
+```python
+from automation_file import execute_action_dag
+
+execute_action_dag([
+    {"id": "fetch",  "action": ["FA_download_file",
+                                ["https://example.com/src.tar.gz", "src.tar.gz"]]},
+    {"id": "verify", "action": ["FA_verify_checksum",
+                                ["src.tar.gz", "3b0c44298fc1..."]],
+                     "depends_on": ["fetch"]},
+    {"id": "unpack", "action": ["FA_unzip_file", ["src.tar.gz", "src"]],
+                     "depends_on": ["verify"]},
+])
+```
+
+If `verify` raises, `unpack` is marked `skipped` by default. Pass
+`fail_fast=False` to run dependents regardless. JSON action:
+`FA_execute_action_dag`.
+
+### Entry-point plugins
+Third-party packages advertise actions via `pyproject.toml`:
+
+```toml
+[project.entry-points."automation_file.actions"]
+my_plugin = "my_plugin:register"
+```
+
+where `register` is a zero-argument callable returning a
+`dict[str, Callable]`. Once installed in the same environment, the
+commands show up in every freshly-built registry:
+
+```python
+# my_plugin/__init__.py
+def greet(name: str) -> str:
+    return f"hello {name}"
+
+def register() -> dict:
+    return {"FA_greet": greet}
+```
+
+```python
+# after `pip install my_plugin`
+from automation_file import execute_action
+execute_action([["FA_greet", {"name": "world"}]])
+```
+
+Plugin failures are logged and swallowed — one broken plugin cannot
+break the library.
+
 ### GUI
 ```bash
 python -m automation_file ui        # or: python main_ui.py
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 632be63..f832cbb 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -18,6 +18,11 @@ TCP / HTTP 服务器执行的 JSON 驱动动作。内附 PySide6 GUI，每个功
 - **Cron 调度器** — 仅用标准库的 5 字段解析器执行周期性动作清单（`FA_schedule_*`）
 - **传输进度 + 取消** — HTTP 与 S3 传输可选的 `progress_name` 钩子（`FA_progress_*`）
 - **快速文件搜索** — OS 索引快速路径（`mdfind` / `locate` / `es.exe`）搭配流式 `scandir` 回退（`FA_fast_find`）
+- **校验和 + 完整性验证** — 流式 `file_checksum` / `verify_checksum`，支持任何 `hashlib` 算法；`download_file(expected_sha256=...)` 在下载完成后立即验证（`FA_file_checksum`、`FA_verify_checksum`）
+- **可续传 HTTP 下载** — `download_file(resume=True)` 写入 `<target>.part` 并发送 `Range: bytes=<n>-`，让中断的传输继续而非从头开始
+- **重复文件查找器** — 三阶段 size → 部分哈希 → 完整哈希管线；大小唯一的文件完全不会被哈希（`FA_find_duplicates`）
+- **DAG 动作执行器** — 按依赖顺序拓扑调度，独立分支并行展开，失败时其后代默认标记为跳过（`FA_execute_action_dag`）
+- **Entry-point 插件** — 第三方包通过 `[project.entry-points."automation_file.actions"]` 注册自定义 `FA_*` 动作；`build_default_registry()` 会自动加载
 - PySide6 GUI（`python -m automation_file ui`）每个后端一个页签，含 JSON 动作执行器，另有 Triggers、Scheduler、实时 Progress 专属页签
 - 功能丰富的 CLI，包含一次性子命令与旧式 JSON 批量标志
 - 项目脚手架（`ProjectBuilder`）协助构建以 executor 为核心的自动化项目
@@ -340,6 +345,98 @@ for path in scandir_find("/data", "*.csv"):
 [["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
 ```
 
+### 校验和 + 完整性验证
+流式处理任何 `hashlib` 算法；`verify_checksum` 使用 `hmac.compare_digest`
+（常数时间）比较摘要：
+
+```python
+from automation_file import file_checksum, verify_checksum
+
+digest = file_checksum("bundle.tar.gz")                # 默认为 sha256
+verify_checksum("bundle.tar.gz", digest)               # -> True
+verify_checksum("bundle.tar.gz", "deadbeef...", algorithm="blake2b")
+```
+
+同时以 `FA_file_checksum` / `FA_verify_checksum` 提供 JSON 动作。
+
+### 可续传 HTTP 下载
+`download_file(resume=True)` 会写入 `<target>.part` 并在下次尝试时发送
+`Range: bytes=<n>-`。配合 `expected_sha256=` 可在下载完成后立即验证完整性：
+
+```python
+from automation_file import download_file
+
+download_file(
+    "https://example.com/big.bin",
+    "big.bin",
+    resume=True,
+    expected_sha256="3b0c44298fc1...",
+)
+```
+
+### 重复文件查找器
+三阶段管线：按大小分桶 → 64 KiB 部分哈希 → 完整哈希。大小唯一的文件完全不会
+被哈希：
+
+```python
+from automation_file import find_duplicates
+
+groups = find_duplicates("/data", min_size=1024)
+# list[list[str]] — 每个内层 list 是一组相同内容的文件，按大小降序排序。
+```
+
+`FA_find_duplicates` 以相同调用提供给 JSON。
+
+### DAG 动作执行器
+按依赖顺序执行动作；独立分支通过线程池并行展开。每个节点的形式为
+`{"id": ..., "action": [...], "depends_on": [...]}`：
+
+```python
+from automation_file import execute_action_dag
+
+execute_action_dag([
+    {"id": "fetch",  "action": ["FA_download_file",
+                                ["https://example.com/src.tar.gz", "src.tar.gz"]]},
+    {"id": "verify", "action": ["FA_verify_checksum",
+                                ["src.tar.gz", "3b0c44298fc1..."]],
+                     "depends_on": ["fetch"]},
+    {"id": "unpack", "action": ["FA_unzip_file", ["src.tar.gz", "src"]],
+                     "depends_on": ["verify"]},
+])
+```
+
+若 `verify` 抛出异常，默认情况下 `unpack` 会被标记为 `skipped`。传入
+`fail_fast=False` 可让后代节点仍然执行。JSON 动作：`FA_execute_action_dag`。
+
+### Entry-point 插件
+第三方包通过 `pyproject.toml` 声明动作：
+
+```toml
+[project.entry-points."automation_file.actions"]
+my_plugin = "my_plugin:register"
+```
+
+其中 `register` 是一个零参数的可调用对象，返回 `dict[str, Callable]`。只要
+包被安装在同一个虚拟环境，这些命令就会出现在每次新建的 registry 中：
+
+```python
+# my_plugin/__init__.py
+def greet(name: str) -> str:
+    return f"hello {name}"
+
+def register() -> dict:
+    return {"FA_greet": greet}
+```
+
+```python
+# 执行 `pip install my_plugin` 之后
+from automation_file import execute_action
+execute_action([["FA_greet", {"name": "world"}]])
+```
+
+插件失败（导入错误、factory 异常、返回类型不正确、registry 拒绝）都会被记录
+并吞掉 — 一个坏掉的插件不会影响整个库。
+
 ### GUI
 ```bash
 python -m automation_file ui        # 或：python main_ui.py
diff --git a/README.zh-TW.md b/README.zh-TW.md
index 6fcc4b3..0aaed5f 100644
--- a/README.zh-TW.md
+++ b/README.zh-TW.md
@@ -18,6 +18,11 @@ TCP / HTTP 伺服器執行的 JSON 驅動動作。內附 PySide6 GUI，每個功
 - **Cron 排程器** — 僅用標準函式庫的 5 欄位解析器執行週期性動作清單（`FA_schedule_*`）
 - **傳輸進度 + 取消** — HTTP 與 S3 傳輸可選的 `progress_name` 掛鉤（`FA_progress_*`）
 - **快速檔案搜尋** — OS 索引快速路徑（`mdfind` / `locate` / `es.exe`）搭配串流式 `scandir` 備援（`FA_fast_find`）
+- **檢查碼 + 完整性驗證** — 串流式 `file_checksum` / `verify_checksum`，支援任何 `hashlib` 演算法；`download_file(expected_sha256=...)` 於下載完成後立即驗證（`FA_file_checksum`、`FA_verify_checksum`）
+- **可續傳 HTTP 下載** — `download_file(resume=True)` 寫入 `<target>.part` 並傳送 `Range: bytes=<n>-`，讓中斷的傳輸繼續而非從頭開始
+- **重複檔案尋找器** — 三階段 size → 部分雜湊 → 完整雜湊管線；大小唯一的檔案完全不會被雜湊（`FA_find_duplicates`）
+- **DAG 動作執行器** — 依相依順序拓撲排程，獨立分支平行展開，失敗時其後代預設標記跳過（`FA_execute_action_dag`）
+- **Entry-point 外掛** — 第三方套件透過 `[project.entry-points."automation_file.actions"]` 註冊自訂 `FA_*` 動作；`build_default_registry()` 會自動載入
 - PySide6 GUI（`python -m automation_file ui`）每個後端一個分頁，含 JSON 動作執行器，另有 Triggers、Scheduler、即時 Progress 專屬分頁
 - 功能豐富的 CLI，包含一次性子指令與舊式 JSON 批次旗標
 - 專案鷹架（`ProjectBuilder`）協助建立以 executor 為核心的自動化專案
@@ -340,6 +345,98 @@ for path in scandir_find("/data", "*.csv"):
 [["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
 ```
 
+### 檢查碼 + 完整性驗證
+串流式處理任何 `hashlib` 演算法；`verify_checksum` 以 `hmac.compare_digest`
+（常數時間）比對摘要：
+
+```python
+from automation_file import file_checksum, verify_checksum
+
+digest = file_checksum("bundle.tar.gz")                # 預設為 sha256
+verify_checksum("bundle.tar.gz", digest)               # -> True
+verify_checksum("bundle.tar.gz", "deadbeef...", algorithm="blake2b")
+```
+
+同時以 `FA_file_checksum` / `FA_verify_checksum` 提供 JSON 動作。
+
+### 可續傳 HTTP 下載
+`download_file(resume=True)` 會寫入 `<target>.part` 並於下次嘗試傳送
+`Range: bytes=<n>-`。搭配 `expected_sha256=` 可在下載完成後立刻驗證完整性：
+
+```python
+from automation_file import download_file
+
+download_file(
+    "https://example.com/big.bin",
+    "big.bin",
+    resume=True,
+    expected_sha256="3b0c44298fc1...",
+)
+```
+
+### 重複檔案尋找器
+三階段管線：依大小分桶 → 64 KiB 部分雜湊 → 完整雜湊。大小唯一的檔案完全不會
+被雜湊：
+
+```python
+from automation_file import find_duplicates
+
+groups = find_duplicates("/data", min_size=1024)
+# list[list[str]] — 每個內層 list 是一組相同內容的檔案，以大小遞減排序。
+```
+
+`FA_find_duplicates` 以相同呼叫提供給 JSON。
+
+### DAG 動作執行器
+依相依關係執行動作；獨立分支會透過執行緒池平行展開。每個節點形式為
+`{"id": ..., "action": [...], "depends_on": [...]}`：
+
+```python
+from automation_file import execute_action_dag
+
+execute_action_dag([
+    {"id": "fetch",  "action": ["FA_download_file",
+                                ["https://example.com/src.tar.gz", "src.tar.gz"]]},
+    {"id": "verify", "action": ["FA_verify_checksum",
+                                ["src.tar.gz", "3b0c44298fc1..."]],
+                     "depends_on": ["fetch"]},
+    {"id": "unpack", "action": ["FA_unzip_file", ["src.tar.gz", "src"]],
+                     "depends_on": ["verify"]},
+])
+```
+
+若 `verify` 拋出例外，預設情況下 `unpack` 會被標記為 `skipped`。傳入
+`fail_fast=False` 可讓後代節點仍然執行。JSON 動作：`FA_execute_action_dag`。
+
+### Entry-point 外掛
+第三方套件以 `pyproject.toml` 宣告動作：
+
+```toml
+[project.entry-points."automation_file.actions"]
+my_plugin = "my_plugin:register"
+```
+
+其中 `register` 是一個零參數的可呼叫物件，回傳 `dict[str, Callable]`。只要
+套件被安裝於同一個虛擬環境，這些指令就會出現在每次新建的 registry：
+
+```python
+# my_plugin/__init__.py
+def greet(name: str) -> str:
+    return f"hello {name}"
+
+def register() -> dict:
+    return {"FA_greet": greet}
+```
+
+```python
+# 執行 `pip install my_plugin` 之後
+from automation_file import execute_action
+execute_action([["FA_greet", {"name": "world"}]])
+```
+
+外掛失敗（匯入錯誤、factory 例外、回傳型別不正確、registry 拒絕）都會被記錄
+並吞掉 — 一個壞掉的外掛不會影響整個函式庫。
+
 ### GUI
 ```bash
 python -m automation_file ui        # 或：python main_ui.py
diff --git a/docs/source/api/core.rst b/docs/source/api/core.rst
index 3d6111f..78fbb88 100644
--- a/docs/source/api/core.rst
+++ b/docs/source/api/core.rst
@@ -7,6 +7,9 @@ Core
 .. automodule:: automation_file.core.action_executor
    :members:
 
+.. automodule:: automation_file.core.dag_executor
+   :members:
+
 .. automodule:: automation_file.core.callback_executor
    :members:
 
@@ -22,6 +25,12 @@ Core
 .. automodule:: automation_file.core.quota
    :members:
 
+.. automodule:: automation_file.core.checksum
+   :members:
+
+.. automodule:: automation_file.core.plugins
+   :members:
+
 .. automodule:: automation_file.exceptions
    :members:
 
diff --git a/docs/source/api/utils.rst b/docs/source/api/utils.rst
index a4e7876..41358da 100644
--- a/docs/source/api/utils.rst
+++ b/docs/source/api/utils.rst
@@ -6,3 +6,6 @@ Utils
 
 .. automodule:: automation_file.utils.fast_find
    :members:
+
+.. automodule:: automation_file.utils.deduplicate
+   :members:
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
index 6f7235f..041db3b 100644
--- a/docs/source/architecture.rst
+++ b/docs/source/architecture.rst
@@ -48,11 +48,14 @@ Module layout
    ├── core/
    │   ├── action_registry.py
    │   ├── action_executor.py   # serial, parallel, dry-run, validate-first
+   │   ├── dag_executor.py      # topological scheduler with parallel fan-out
    │   ├── callback_executor.py
    │   ├── package_loader.py
+   │   ├── plugins.py           # entry-point plugin discovery
    │   ├── json_store.py
    │   ├── retry.py             # @retry_on_transient
    │   ├── quota.py             # Quota(max_bytes, max_seconds)
+   │   ├── checksum.py          # file_checksum, verify_checksum
    │   └── progress.py          # CancellationToken, ProgressReporter, progress_registry
    ├── local/
    │   ├── file_ops.py
@@ -88,12 +91,13 @@ Module layout
    │   └── tabs/                # one tab per backend + JSON runner + servers
    └── utils/
        ├── file_discovery.py
-       └── fast_find.py         # OS-index (mdfind/locate/es) + scandir fallback
+       ├── fast_find.py         # OS-index (mdfind/locate/es) + scandir fallback
+       └── deduplicate.py       # size → partial-hash → full-hash dedup pipeline
 
 Execution modes
 ---------------
 
-The shared executor supports four orthogonal modes:
+The shared executor supports five orthogonal modes:
 
 * ``execute_action(actions)`` — default serial execution; each failure is
   captured and reported without aborting the batch.
@@ -105,6 +109,12 @@ The shared executor supports four orthogonal modes:
 * ``execute_action_parallel(actions, max_workers=4)`` — dispatch actions
   concurrently through a thread pool. The caller is responsible for ensuring
   the chosen actions are independent.
+* ``execute_action_dag(nodes, max_workers=4, fail_fast=True)`` — Kahn-style
+  topological scheduling. Each node is ``{"id": str, "action": [...],
+  "depends_on": [id, ...]}``. Independent branches run in parallel, failed
+  branches mark their transitive dependents ``skipped`` (or still run them
+  under ``fail_fast=False``). Cycles / unknown deps / duplicate ids are
+  rejected before any node runs.
 
 Reliability utilities
 ---------------------
@@ -114,6 +124,18 @@ Reliability utilities
   exponential back-off. Used by :func:`automation_file.download_file`.
 * :class:`automation_file.core.quota.Quota` — dataclass bundling an optional
   ``max_bytes`` size cap and an optional ``max_seconds`` time budget.
+* :func:`automation_file.core.checksum.file_checksum` and
+  :func:`automation_file.core.checksum.verify_checksum` — streaming file
+  hashing (any :mod:`hashlib` algorithm) with constant-time digest comparison.
+  :func:`automation_file.download_file` accepts ``expected_sha256=`` to
+  verify the target immediately after the HTTP transfer completes.
+* Resumable downloads: :func:`automation_file.download_file` accepts
+  ``resume=True``, which writes to ``<target>.part`` and sends
+  ``Range: bytes=<n>-`` so interrupted transfers continue from the existing
+  byte count instead of restarting from zero.
+* :func:`automation_file.utils.deduplicate.find_duplicates` — three-stage
+  size → partial-hash → full-hash pipeline; most files never get hashed
+  because unique-size buckets are discarded before any digest is read.
 * :class:`automation_file.core.progress.CancellationToken` and
   :class:`automation_file.core.progress.ProgressReporter` — opt-in per-transfer
   instrumentation. HTTP download and S3 upload/download accept a
@@ -156,6 +178,31 @@ Security boundaries
   :class:`paramiko.RejectPolicy` and never auto-adds unknown host keys.
 * **Plugin loading**: :class:`automation_file.core.package_loader.PackageLoader`
   registers arbitrary module members; never expose it to untrusted input.
+  The entry-point discovery path
+  (:func:`automation_file.core.plugins.load_entry_point_plugins`) is safer —
+  only packages the user has explicitly installed can contribute commands —
+  but every plugin still runs with full library privileges, so review
+  third-party plugins before installing them.
+
+Entry-point plugins
+-------------------
+
+Third-party packages can ship extra actions without ``automation_file``
+having to import them. A plugin advertises itself in its
+``pyproject.toml``::
+
+   [project.entry-points."automation_file.actions"]
+   my_plugin = "my_plugin:register"
+
+where ``register`` is a zero-argument callable returning a
+``Mapping[str, Callable]`` — the same shape you would hand to
+:func:`automation_file.add_command_to_executor`.
+:func:`automation_file.core.action_registry.build_default_registry`
+invokes :func:`automation_file.core.plugins.load_entry_point_plugins` after
+the built-ins are wired in, so installed plugins populate every
+freshly-built registry automatically. Plugin failures (import errors,
+factory exceptions, bad return shape, registry rejection) are logged and
+swallowed so one broken plugin does not break the library.
 
 Shared singletons
 -----------------
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 23eaaa3..1f03b4b 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -288,6 +288,125 @@ The same action is available to JSON action lists as ``FA_fast_find``:
 
    [["FA_fast_find", {"root": "/var/log", "pattern": "*.log", "limit": 50}]]
 
+Checksums and integrity verification
+------------------------------------
+
+Hash any file with a streaming reader (any :mod:`hashlib` algorithm) and
+verify it against an expected digest using constant-time comparison:
+
+.. code-block:: python
+
+   from automation_file import file_checksum, verify_checksum
+
+   digest = file_checksum("bundle.tar.gz")                 # sha256 by default
+   verify_checksum("bundle.tar.gz", digest)                # -> True
+   verify_checksum("bundle.tar.gz", "deadbeef...", algorithm="blake2b")
+
+The same functions are available to JSON action lists as
+``FA_file_checksum`` and ``FA_verify_checksum``.
+
+Resumable HTTP downloads
+------------------------
+
+:func:`~automation_file.download_file` accepts ``resume=True``. Bytes are
+written to ``<target>.part``; if the tempfile already exists the next call
+sends ``Range: bytes=<n>-`` so the transfer picks up where it left off.
+Combined with ``expected_sha256=`` the download is verified immediately
+after the last chunk is written:
+
+.. code-block:: python
+
+   from automation_file import download_file
+
+   download_file(
+       "https://example.com/big.bin",
+       "big.bin",
+       resume=True,
+       expected_sha256="3b0c44298fc1...",
+   )
+
+File deduplication
+------------------
+
+:func:`~automation_file.find_duplicates` walks a tree once with
+``os.scandir`` and runs a three-stage size → partial-hash → full-hash
+pipeline. Files with unique sizes are eliminated without being hashed at
+all, so a tree of millions of files is cheap to scan:
+
+.. code-block:: python
+
+   from automation_file import find_duplicates
+
+   groups = find_duplicates("/data", min_size=1024)
+   # groups: list[list[str]], each inner list is a set of identical files
+   # sorted by size descending.
+
+``FA_find_duplicates`` exposes the same call to JSON action lists.
+
+DAG action executor
+-------------------
+
+:func:`~automation_file.execute_action_dag` runs actions in dependency
+order. Each node is ``{"id": str, "action": [name, ...], "depends_on":
+[id, ...]}``. Independent branches fan out across a thread pool; when a
+node fails, its transitive dependents are marked ``skipped``
+(``fail_fast=True``, the default) or still run (``fail_fast=False``):
+
+.. code-block:: python
+
+   from automation_file import execute_action_dag
+
+   results = execute_action_dag([
+       {"id": "fetch",  "action": ["FA_download_file",
+                                   ["https://example.com/src.tar.gz", "src.tar.gz"]]},
+       {"id": "verify", "action": ["FA_verify_checksum",
+                                   ["src.tar.gz", "3b0c44298fc1..."]],
+                        "depends_on": ["fetch"]},
+       {"id": "unpack", "action": ["FA_unzip_file", ["src.tar.gz", "src"]],
+                        "depends_on": ["verify"]},
+       {"id": "report", "action": ["FA_fast_find", ["src", "*.py"]],
+                        "depends_on": ["unpack"]},
+   ])
+
+Cycles, unknown dependencies, self-dependencies, and duplicate ids raise
+:class:`~automation_file.exceptions.DagException` before any node runs.
+The JSON-action form is ``FA_execute_action_dag``.
+
+Entry-point plugins
+-------------------
+
+Third-party packages can register their own ``FA_*`` commands by
+declaring an ``automation_file.actions`` entry point in their
+``pyproject.toml``::
+
+   [project.entry-points."automation_file.actions"]
+   my_plugin = "my_plugin:register"
+
+where ``register`` is a zero-argument callable returning a
+``Mapping[str, Callable]``. Once the plugin is installed into the same
+virtual environment,
+:func:`~automation_file.core.action_registry.build_default_registry`
+picks it up automatically — no caller changes required:
+
+.. code-block:: python
+
+   # my_plugin/__init__.py
+   def greet(name: str) -> str:
+       return f"hello {name}"
+
+   def register() -> dict:
+       return {"FA_greet": greet}
+
+.. code-block:: python
+
+   # consumer code, after `pip install my_plugin`
+   from automation_file import execute_action
+   execute_action([["FA_greet", {"name": "world"}]])
+
+Plugin failures (import errors, factory exceptions, wrong return shape,
+registry rejection) are logged and swallowed so one broken plugin cannot
+break the library.
+
 GUI (PySide6)
 -------------
 

From b32df51d90de209d09ff53ede733e7cdf9a03074 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 21:29:22 +0800
Subject: [PATCH 12/38] Add notification sinks (webhook/Slack/email) with
 fanout manager

---
 automation_file/__init__.py             |  21 ++
 automation_file/core/action_registry.py |   7 +
 automation_file/notify/__init__.py      |  36 +++
 automation_file/notify/manager.py       | 169 ++++++++++++++
 automation_file/notify/sinks.py         | 211 +++++++++++++++++
 automation_file/scheduler/manager.py    |   2 +
 automation_file/trigger/manager.py      |   2 +
 tests/test_notify.py                    | 287 ++++++++++++++++++++++++
 8 files changed, 735 insertions(+)
 create mode 100644 automation_file/notify/__init__.py
 create mode 100644 automation_file/notify/manager.py
 create mode 100644 automation_file/notify/sinks.py
 create mode 100644 tests/test_notify.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index be20fb0..90bd356 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -61,6 +61,17 @@
     zip_file_info,
     zip_info,
 )
+from automation_file.notify import (
+    EmailSink,
+    NotificationException,
+    NotificationManager,
+    NotificationSink,
+    SlackSink,
+    WebhookSink,
+    notification_manager,
+    notify_send,
+    register_notify_ops,
+)
 from automation_file.project.project_builder import ProjectBuilder, create_project_dir
 from automation_file.remote.azure_blob import (
     AzureBlobClient,
@@ -263,6 +274,16 @@ def __getattr__(name: str) -> Any:
     "progress_list",
     "progress_registry",
     "register_progress_ops",
+    # Notifications
+    "EmailSink",
+    "NotificationException",
+    "NotificationManager",
+    "NotificationSink",
+    "SlackSink",
+    "WebhookSink",
+    "notification_manager",
+    "notify_send",
+    "register_notify_ops",
     # UI (lazy-loaded)
     "launch_ui",
 ]
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index bf1238f..391b6d4 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -183,6 +183,12 @@ def _register_progress_ops(registry: ActionRegistry) -> None:
     register_progress_ops(registry)
 
 
+def _register_notify_ops(registry: ActionRegistry) -> None:
+    from automation_file.notify import register_notify_ops
+
+    register_notify_ops(registry)
+
+
 def build_default_registry() -> ActionRegistry:
     """Return a registry pre-populated with every built-in ``FA_*`` action.
 
@@ -199,6 +205,7 @@ def build_default_registry() -> ActionRegistry:
     _register_trigger_ops(registry)
     _register_scheduler_ops(registry)
     _register_progress_ops(registry)
+    _register_notify_ops(registry)
     _load_plugins(registry)
     file_automation_logger.info(
         "action_registry: built default registry with %d commands", len(registry)
diff --git a/automation_file/notify/__init__.py b/automation_file/notify/__init__.py
new file mode 100644
index 0000000..1191a04
--- /dev/null
+++ b/automation_file/notify/__init__.py
@@ -0,0 +1,36 @@
+"""Notification sinks — webhook, Slack, email — wired through a fanout manager.
+
+Every sink exposes the same :meth:`NotificationSink.send` contract so the
+manager can dispatch to many channels from one call site. The manager
+deduplicates identical messages within a sliding window so a stuck
+trigger cannot flood the channel, and it catches per-sink failures so one
+broken sink cannot starve the others.
+"""
+
+from __future__ import annotations
+
+from automation_file.notify.manager import (
+    NotificationException,
+    NotificationManager,
+    notification_manager,
+    notify_send,
+    register_notify_ops,
+)
+from automation_file.notify.sinks import (
+    EmailSink,
+    NotificationSink,
+    SlackSink,
+    WebhookSink,
+)
+
+__all__ = [
+    "EmailSink",
+    "NotificationException",
+    "NotificationManager",
+    "NotificationSink",
+    "SlackSink",
+    "WebhookSink",
+    "notification_manager",
+    "notify_send",
+    "register_notify_ops",
+]
diff --git a/automation_file/notify/manager.py b/automation_file/notify/manager.py
new file mode 100644
index 0000000..f50b996
--- /dev/null
+++ b/automation_file/notify/manager.py
@@ -0,0 +1,169 @@
+"""Notification fanout manager.
+
+Owns a set of registered :class:`NotificationSink` instances and exposes
+one :meth:`NotificationManager.notify` entry point. Per-sink failures are
+logged and swallowed so one broken sink cannot starve the others.
+
+A sliding deduplication window drops identical ``(subject, body, level)``
+messages seen within the window, which is the minimum safety net against
+a stuck trigger flooding a channel. ``dedup_seconds=0`` disables the
+guard.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any
+
+from automation_file.core.action_registry import ActionRegistry
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+from automation_file.notify.sinks import (
+    NotificationException,
+    NotificationSink,
+    _describe,
+)
+
+_DEFAULT_DEDUP_SECONDS = 60.0
+
+
+class NotificationManager:
+    """Fanout to registered sinks with dedup + per-sink error isolation."""
+
+    def __init__(self, dedup_seconds: float = _DEFAULT_DEDUP_SECONDS) -> None:
+        self._lock = threading.Lock()
+        self._sinks: dict[str, NotificationSink] = {}
+        self._recent: dict[tuple[str, str, str], float] = {}
+        self.dedup_seconds = float(dedup_seconds)
+
+    def register(self, sink: NotificationSink) -> None:
+        """Register a sink under its ``sink.name`` (overwrites existing)."""
+        if not isinstance(sink, NotificationSink):
+            raise NotificationException(f"expected NotificationSink, got {type(sink).__name__}")
+        with self._lock:
+            self._sinks[sink.name] = sink
+        file_automation_logger.info(
+            "notify: registered sink %r (%s)", sink.name, type(sink).__name__
+        )
+
+    def unregister(self, name: str) -> bool:
+        """Remove the sink registered under ``name``. Returns ``True`` if found."""
+        with self._lock:
+            removed = self._sinks.pop(name, None) is not None
+        if removed:
+            file_automation_logger.info("notify: unregistered sink %r", name)
+        return removed
+
+    def unregister_all(self) -> int:
+        with self._lock:
+            count = len(self._sinks)
+            self._sinks.clear()
+            self._recent.clear()
+        return count
+
+    def list(self) -> list[dict[str, Any]]:
+        with self._lock:
+            sinks = list(self._sinks.values())
+        return [_describe(sink) for sink in sinks]
+
+    def notify(
+        self,
+        subject: str,
+        body: str = "",
+        level: str = "info",
+    ) -> dict[str, Any]:
+        """Fan ``(subject, body, level)`` out to every registered sink.
+
+        Returns a per-sink status dict: ``{name: "sent" | "dedup" | <error-repr>}``.
+        Missing sinks return an empty dict — callers can use that to detect
+        an unconfigured notifier rather than silently succeeding.
+        """
+        if not isinstance(subject, str) or not subject:
+            raise NotificationException("subject must be a non-empty string")
+        with self._lock:
+            sinks = list(self._sinks.values())
+            if self._should_dedup(subject, body, level):
+                return {sink.name: "dedup" for sink in sinks}
+        results: dict[str, Any] = {}
+        for sink in sinks:
+            results[sink.name] = self._deliver(sink, subject, body, level)
+        return results
+
+    def _deliver(
+        self,
+        sink: NotificationSink,
+        subject: str,
+        body: str,
+        level: str,
+    ) -> str:
+        try:
+            sink.send(subject, body, level)
+        except NotificationException as err:
+            file_automation_logger.error("notify: sink %r failed: %r", sink.name, err)
+            return repr(err)
+        except Exception as err:  # pylint: disable=broad-except
+            file_automation_logger.error("notify: sink %r raised unexpectedly: %r", sink.name, err)
+            return repr(err)
+        return "sent"
+
+    def _should_dedup(self, subject: str, body: str, level: str) -> bool:
+        if self.dedup_seconds <= 0.0:
+            return False
+        key = (subject, body, level)
+        now = time.monotonic()
+        self._prune(now)
+        if key in self._recent:
+            return True
+        self._recent[key] = now
+        return False
+
+    def _prune(self, now: float) -> None:
+        cutoff = now - self.dedup_seconds
+        stale = [key for key, ts in self._recent.items() if ts < cutoff]
+        for key in stale:
+            self._recent.pop(key, None)
+
+
+notification_manager: NotificationManager = NotificationManager()
+
+
+def notify_send(
+    subject: str,
+    body: str = "",
+    level: str = "info",
+) -> dict[str, Any]:
+    """Module-level shim that dispatches through :data:`notification_manager`."""
+    return notification_manager.notify(subject, body, level)
+
+
+def notify_list() -> list[dict[str, Any]]:
+    """Return a description of every registered sink."""
+    return notification_manager.list()
+
+
+def notify_on_failure(context: str, error: FileAutomationException | Exception) -> None:
+    """Helper for auto-notify hooks — sends an ``error``-level message.
+
+    Does nothing when no sinks are registered, so callers can call this
+    unconditionally without having to check the configuration.
+    """
+    with notification_manager._lock:
+        if not notification_manager._sinks:
+            return
+    try:
+        notification_manager.notify(
+            f"automation_file: {context} failed", repr(error), level="error"
+        )
+    except NotificationException as err:
+        file_automation_logger.error("notify_on_failure: manager rejected message: %r", err)
+
+
+def register_notify_ops(registry: ActionRegistry) -> None:
+    """Wire ``FA_notify_*`` actions into a registry."""
+    registry.register_many(
+        {
+            "FA_notify_send": notify_send,
+            "FA_notify_list": notify_list,
+        }
+    )
diff --git a/automation_file/notify/sinks.py b/automation_file/notify/sinks.py
new file mode 100644
index 0000000..bae65d7
--- /dev/null
+++ b/automation_file/notify/sinks.py
@@ -0,0 +1,211 @@
+"""Concrete notification sinks.
+
+Every sink inherits :class:`NotificationSink` and implements ``send``.
+The sinks themselves do no deduplication — that lives in
+:class:`~automation_file.notify.manager.NotificationManager` — so each
+sink can be used standalone from a caller that has already handled
+policy elsewhere.
+"""
+
+from __future__ import annotations
+
+import json
+import smtplib
+from abc import ABC, abstractmethod
+from email.message import EmailMessage
+from typing import Any, ClassVar
+
+import requests
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.remote.url_validator import validate_http_url
+
+LEVELS = frozenset({"info", "warning", "error"})
+_DEFAULT_TIMEOUT = 10.0
+_MAX_BODY_BYTES = 64 * 1024
+
+
+class NotificationException(FileAutomationException):
+    """Raised for misconfigured or failing notification sinks."""
+
+
+class NotificationSink(ABC):
+    """Contract for a single delivery channel."""
+
+    name: str
+
+    @abstractmethod
+    def send(self, subject: str, body: str, level: str = "info") -> None:
+        """Deliver one message. Raise :class:`NotificationException` on failure."""
+
+    @staticmethod
+    def _check_level(level: str) -> str:
+        if level not in LEVELS:
+            raise NotificationException(f"level must be one of {sorted(LEVELS)}, got {level!r}")
+        return level
+
+    @staticmethod
+    def _truncate(body: str) -> str:
+        encoded = body.encode("utf-8", errors="replace")
+        if len(encoded) <= _MAX_BODY_BYTES:
+            return body
+        return encoded[:_MAX_BODY_BYTES].decode("utf-8", errors="replace") + "…[truncated]"
+
+
+class WebhookSink(NotificationSink):
+    """Generic JSON webhook sink — POSTs ``{subject, body, level}`` to ``url``."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        name: str = "webhook",
+        timeout: float = _DEFAULT_TIMEOUT,
+        extra_headers: dict[str, str] | None = None,
+    ) -> None:
+        validate_http_url(url)
+        self.url = url
+        self.name = name
+        self.timeout = timeout
+        self.extra_headers = dict(extra_headers or {})
+
+    def send(self, subject: str, body: str, level: str = "info") -> None:
+        self._check_level(level)
+        payload = {"subject": subject, "body": self._truncate(body), "level": level}
+        headers = {"Content-Type": "application/json"}
+        headers.update(self.extra_headers)
+        try:
+            response = requests.post(
+                self.url,
+                data=json.dumps(payload).encode("utf-8"),
+                headers=headers,
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException as err:
+            raise NotificationException(f"webhook {self.name!r} post failed: {err}") from err
+        if response.status_code >= 400:
+            raise NotificationException(
+                f"webhook {self.name!r} returned HTTP {response.status_code}"
+            )
+
+
+class SlackSink(NotificationSink):
+    """Slack incoming-webhook sink.
+
+    ``webhook_url`` is the full ``https://hooks.slack.com/services/...`` URL
+    and is treated as a secret — it is not logged. The level controls a
+    plain-text prefix (:warning:, :rotating_light:) prepended to the body.
+    """
+
+    _LEVEL_PREFIX: ClassVar[dict[str, str]] = {
+        "info": "",
+        "warning": ":warning: ",
+        "error": ":rotating_light: ",
+    }
+
+    def __init__(
+        self,
+        webhook_url: str,
+        *,
+        name: str = "slack",
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        validate_http_url(webhook_url)
+        self._url = webhook_url
+        self.name = name
+        self.timeout = timeout
+
+    def send(self, subject: str, body: str, level: str = "info") -> None:
+        self._check_level(level)
+        prefix = self._LEVEL_PREFIX[level]
+        text = f"{prefix}*{subject}*\n{self._truncate(body)}"
+        payload = {"text": text}
+        try:
+            response = requests.post(
+                self._url,
+                data=json.dumps(payload).encode("utf-8"),
+                headers={"Content-Type": "application/json"},
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException as err:
+            raise NotificationException(f"slack sink {self.name!r} post failed: {err}") from err
+        if response.status_code >= 400:
+            raise NotificationException(
+                f"slack sink {self.name!r} returned HTTP {response.status_code}"
+            )
+
+
+class EmailSink(NotificationSink):
+    """SMTP sink.
+
+    Credentials never appear in the sink's ``repr``; the password is only
+    held as an instance attribute and used once per ``send``.
+    """
+
+    def __init__(
+        self,
+        *,
+        host: str,
+        port: int,
+        sender: str,
+        recipients: list[str],
+        username: str | None = None,
+        password: str | None = None,
+        use_tls: bool = True,
+        name: str = "email",
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        if not recipients:
+            raise NotificationException("email sink requires at least one recipient")
+        self.host = host
+        self.port = int(port)
+        self.sender = sender
+        self.recipients = list(recipients)
+        self._username = username
+        self._password = password
+        self.use_tls = bool(use_tls)
+        self.name = name
+        self.timeout = timeout
+
+    def send(self, subject: str, body: str, level: str = "info") -> None:
+        self._check_level(level)
+        message = EmailMessage()
+        message["Subject"] = f"[{level.upper()}] {subject}"
+        message["From"] = self.sender
+        message["To"] = ", ".join(self.recipients)
+        message.set_content(self._truncate(body))
+        try:
+            with smtplib.SMTP(self.host, self.port, timeout=self.timeout) as client:
+                if self.use_tls:
+                    client.starttls()
+                if self._username and self._password:
+                    client.login(self._username, self._password)
+                client.send_message(message)
+        except (OSError, smtplib.SMTPException) as err:
+            raise NotificationException(f"email sink {self.name!r} send failed: {err}") from err
+
+    def __repr__(self) -> str:
+        return (
+            f"EmailSink(name={self.name!r}, host={self.host!r}, port={self.port}, "
+            f"sender={self.sender!r}, recipients={self.recipients!r}, "
+            f"use_tls={self.use_tls})"
+        )
+
+
+def _describe(sink: NotificationSink) -> dict[str, Any]:
+    info: dict[str, Any] = {"name": sink.name, "type": type(sink).__name__}
+    if isinstance(sink, WebhookSink):
+        info["url_host"] = _host_of(sink.url)
+    elif isinstance(sink, EmailSink):
+        info["host"] = sink.host
+        info["port"] = sink.port
+        info["recipients"] = sink.recipients
+    return info
+
+
+def _host_of(url: str) -> str:
+    from urllib.parse import urlparse
+
+    return urlparse(url).hostname or ""
diff --git a/automation_file/scheduler/manager.py b/automation_file/scheduler/manager.py
index 398ffc6..c040a9c 100644
--- a/automation_file/scheduler/manager.py
+++ b/automation_file/scheduler/manager.py
@@ -138,11 +138,13 @@ def __contains__(self, name: object) -> bool:
 
 def _safe_execute(job_name: str, action_list: list[list[Any]]) -> None:
     from automation_file.core.action_executor import executor
+    from automation_file.notify.manager import notify_on_failure
 
     try:
         executor.execute_action(action_list)
     except FileAutomationException as error:
         file_automation_logger.warning("scheduler[%s]: dispatch failed: %r", job_name, error)
+        notify_on_failure(f"scheduler[{job_name}]", error)
 
 
 scheduler: Scheduler = Scheduler()
diff --git a/automation_file/trigger/manager.py b/automation_file/trigger/manager.py
index b0af75a..bb101f9 100644
--- a/automation_file/trigger/manager.py
+++ b/automation_file/trigger/manager.py
@@ -66,6 +66,7 @@ def on_any_event(self, event: FileSystemEvent) -> None:
             return
         file_automation_logger.info("trigger[%s]: %s %s", self._name, kind, event.src_path)
         from automation_file.core.action_executor import executor
+        from automation_file.notify.manager import notify_on_failure
 
         try:
             executor.execute_action(self._action_list)
@@ -73,6 +74,7 @@ def on_any_event(self, event: FileSystemEvent) -> None:
             file_automation_logger.warning(
                 "trigger[%s]: action dispatch failed: %r", self._name, error
             )
+            notify_on_failure(f"trigger[{self._name}]", error)
 
 
 class FileWatcher:
diff --git a/tests/test_notify.py b/tests/test_notify.py
new file mode 100644
index 0000000..80ff482
--- /dev/null
+++ b/tests/test_notify.py
@@ -0,0 +1,287 @@
+"""Tests for automation_file.notify."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from automation_file.exceptions import UrlValidationException
+from automation_file.notify import (
+    EmailSink,
+    NotificationException,
+    NotificationManager,
+    NotificationSink,
+    SlackSink,
+    WebhookSink,
+    notification_manager,
+)
+
+
+@pytest.fixture(autouse=True)
+def _reset_manager() -> None:
+    notification_manager.unregister_all()
+    yield
+    notification_manager.unregister_all()
+
+
+class _FakeResp:
+    def __init__(self, status_code: int = 200) -> None:
+        self.status_code = status_code
+
+
+def test_webhook_posts_json() -> None:
+    sink = WebhookSink("https://example.com/hook", name="hook-a")
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(200)
+        sink.send("hello", "body here", "info")
+    post.assert_called_once()
+    kwargs = post.call_args.kwargs
+    assert kwargs["allow_redirects"] is False
+    assert kwargs["timeout"] == 10.0
+    import json
+
+    body = json.loads(kwargs["data"].decode("utf-8"))
+    assert body == {"subject": "hello", "body": "body here", "level": "info"}
+
+
+def test_webhook_rejects_loopback_url() -> None:
+    with pytest.raises(UrlValidationException):
+        WebhookSink("http://127.0.0.1/hook")
+
+
+def test_webhook_rejects_bad_level() -> None:
+    sink = WebhookSink("https://example.com/hook")
+    with pytest.raises(NotificationException, match="level"):
+        sink.send("x", "y", "debug")
+
+
+def test_webhook_http_error_raises() -> None:
+    sink = WebhookSink("https://example.com/hook")
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(500)
+        with pytest.raises(NotificationException, match="HTTP 500"):
+            sink.send("x", "y")
+
+
+def test_slack_prepends_level_prefix() -> None:
+    sink = SlackSink("https://hooks.slack.com/services/T/B/X")
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(200)
+        sink.send("alert", "disk full", "error")
+    kwargs = post.call_args.kwargs
+    import json
+
+    body = json.loads(kwargs["data"].decode("utf-8"))
+    assert body["text"].startswith(":rotating_light: *alert*\n")
+
+
+def test_slack_repr_never_reveals_url() -> None:
+    sink = SlackSink("https://hooks.slack.com/services/T/B/SECRET-TOKEN")
+    assert "SECRET-TOKEN" not in repr(sink)
+
+
+def test_email_send_uses_smtp_context_manager() -> None:
+    sink = EmailSink(
+        host="smtp.example.com",
+        port=587,
+        sender="me@example.com",
+        recipients=["you@example.com"],
+        username="me",
+        password="pw",
+        use_tls=True,
+    )
+    with patch("automation_file.notify.sinks.smtplib.SMTP") as smtp_cls:
+        smtp = MagicMock()
+        smtp_cls.return_value.__enter__.return_value = smtp
+        sink.send("subj", "body", "warning")
+    smtp.starttls.assert_called_once()
+    smtp.login.assert_called_once_with("me", "pw")
+    smtp.send_message.assert_called_once()
+    message = smtp.send_message.call_args[0][0]
+    assert message["Subject"] == "[WARNING] subj"
+
+
+def test_email_repr_hides_password() -> None:
+    sink = EmailSink(
+        host="smtp.example.com",
+        port=587,
+        sender="me@example.com",
+        recipients=["you@example.com"],
+        username="me",
+        password="secret-pw",
+    )
+    assert "secret-pw" not in repr(sink)
+
+
+def test_email_requires_recipients() -> None:
+    with pytest.raises(NotificationException, match="recipient"):
+        EmailSink(
+            host="smtp.example.com",
+            port=25,
+            sender="me@example.com",
+            recipients=[],
+        )
+
+
+def test_manager_fans_out_to_all_sinks() -> None:
+    calls: list[tuple[str, str, str]] = []
+
+    class _Recorder(NotificationSink):
+        name = "rec"
+
+        def send(self, subject: str, body: str, level: str = "info") -> None:
+            calls.append((subject, body, level))
+
+    manager = NotificationManager(dedup_seconds=0.0)
+    manager.register(_Recorder())
+    result = manager.notify("s", "b", "info")
+    assert result == {"rec": "sent"}
+    assert calls == [("s", "b", "info")]
+
+
+def test_manager_dedups_identical_messages() -> None:
+    class _Recorder(NotificationSink):
+        name = "rec"
+        count = 0
+
+        def send(self, subject: str, body: str, level: str = "info") -> None:
+            _Recorder.count += 1
+
+    manager = NotificationManager(dedup_seconds=60.0)
+    manager.register(_Recorder())
+    manager.notify("s", "b", "info")
+    result = manager.notify("s", "b", "info")
+    assert result == {"rec": "dedup"}
+    assert _Recorder.count == 1
+
+
+def test_manager_distinct_messages_both_sent() -> None:
+    class _Recorder(NotificationSink):
+        name = "rec"
+        count = 0
+
+        def send(self, subject: str, body: str, level: str = "info") -> None:
+            _Recorder.count += 1
+
+    manager = NotificationManager(dedup_seconds=60.0)
+    manager.register(_Recorder())
+    manager.notify("s1", "b", "info")
+    manager.notify("s2", "b", "info")
+    assert _Recorder.count == 2
+
+
+def test_manager_isolates_failing_sink() -> None:
+    class _Boom(NotificationSink):
+        name = "boom"
+
+        def send(self, subject: str, body: str, level: str = "info") -> None:
+            raise NotificationException("always broken")
+
+    class _Good(NotificationSink):
+        name = "good"
+        sent = 0
+
+        def send(self, subject: str, body: str, level: str = "info") -> None:
+            _Good.sent += 1
+
+    manager = NotificationManager(dedup_seconds=0.0)
+    manager.register(_Boom())
+    manager.register(_Good())
+    result = manager.notify("s", "b", "info")
+    assert result["good"] == "sent"
+    assert "always broken" in result["boom"]
+    assert _Good.sent == 1
+
+
+def test_manager_unregister() -> None:
+    class _Recorder(NotificationSink):
+        name = "rec"
+
+        def send(self, subject: str, body: str, level: str = "info") -> None:
+            pass
+
+    manager = NotificationManager(dedup_seconds=0.0)
+    manager.register(_Recorder())
+    assert manager.unregister("rec") is True
+    assert manager.unregister("rec") is False
+
+
+def test_notify_send_uses_shared_manager() -> None:
+    from automation_file import notify_send
+
+    class _Recorder(NotificationSink):
+        name = "rec"
+        last: tuple[str, str, str] | None = None
+
+        def send(self, subject: str, body: str, level: str = "info") -> None:
+            _Recorder.last = (subject, body, level)
+
+    notification_manager.register(_Recorder())
+    notify_send("subject", "body", "error")
+    assert _Recorder.last == ("subject", "body", "error")
+
+
+def test_notify_actions_registered() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    registry = build_default_registry()
+    assert "FA_notify_send" in registry
+    assert "FA_notify_list" in registry
+
+
+def test_notify_on_failure_no_op_without_sinks() -> None:
+    from automation_file.notify.manager import notify_on_failure
+
+    # No sinks registered — must not raise.
+    notify_on_failure("ctx", RuntimeError("boom"))
+
+
+def test_notify_on_failure_sends_error_level() -> None:
+    from automation_file.notify.manager import notify_on_failure
+
+    captured: list[tuple[str, str, str]] = []
+
+    class _Recorder(NotificationSink):
+        name = "rec"
+
+        def send(self, subject: str, body: str, level: str = "info") -> None:
+            captured.append((subject, body, level))
+
+    notification_manager.register(_Recorder())
+    notify_on_failure("scheduler[nightly]", RuntimeError("disk full"))
+    assert len(captured) == 1
+    subject, body, level = captured[0]
+    assert level == "error"
+    assert "scheduler[nightly]" in subject
+    assert "disk full" in body
+
+
+def test_long_body_is_truncated() -> None:
+    sink = WebhookSink("https://example.com/hook")
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(200)
+        sink.send("s", "x" * (65 * 1024), "info")
+    kwargs = post.call_args.kwargs
+    import json
+
+    body = json.loads(kwargs["data"].decode("utf-8"))
+    assert body["body"].endswith("…[truncated]")
+
+
+def test_manager_list_describes_sinks() -> None:
+    manager = NotificationManager(dedup_seconds=0.0)
+    manager.register(WebhookSink("https://example.com/hook", name="hook-a"))
+    manager.register(
+        EmailSink(
+            host="smtp.example.com",
+            port=587,
+            sender="me@example.com",
+            recipients=["a@example.com"],
+        )
+    )
+    descriptions = manager.list()
+    assert {d["name"] for d in descriptions} == {"hook-a", "email"}
+    webhook_desc = next(d for d in descriptions if d["name"] == "hook-a")
+    assert webhook_desc["type"] == "WebhookSink"
+    assert webhook_desc["url_host"] == "example.com"

From e7054d9277edbab58e2a3e4b0cce21d1d53ae8ef Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 21:32:02 +0800
Subject: [PATCH 13/38] =?UTF-8?q?Add=20FA=5Fsync=5Fdir=20=E2=80=94=20rsync?=
 =?UTF-8?q?-style=20incremental=20directory=20sync?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 automation_file/__init__.py             |   3 +
 automation_file/core/action_registry.py |   3 +-
 automation_file/local/sync_ops.py       | 186 ++++++++++++++++++++++
 tests/test_sync_ops.py                  | 199 ++++++++++++++++++++++++
 4 files changed, 390 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/local/sync_ops.py
 create mode 100644 tests/test_sync_ops.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 90bd356..898e2ff 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -51,6 +51,7 @@
     rename_file,
 )
 from automation_file.local.safe_paths import is_within, safe_join
+from automation_file.local.sync_ops import SyncException, sync_dir
 from automation_file.local.zip_ops import (
     read_zip_file,
     set_zip_password,
@@ -189,6 +190,8 @@ def __getattr__(name: str) -> Any:
     "create_dir",
     "remove_dir_tree",
     "rename_dir",
+    "sync_dir",
+    "SyncException",
     "zip_dir",
     "zip_file",
     "zip_info",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 391b6d4..f45e07c 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -66,7 +66,7 @@ def event_dict(self) -> dict[str, Command]:
 
 
 def _local_commands() -> dict[str, Command]:
-    from automation_file.local import dir_ops, file_ops, zip_ops
+    from automation_file.local import dir_ops, file_ops, sync_ops, zip_ops
 
     return {
         # Files
@@ -81,6 +81,7 @@ def _local_commands() -> dict[str, Command]:
         "FA_create_dir": dir_ops.create_dir,
         "FA_remove_dir_tree": dir_ops.remove_dir_tree,
         "FA_rename_dir": dir_ops.rename_dir,
+        "FA_sync_dir": sync_ops.sync_dir,
         # Zip
         "FA_zip_dir": zip_ops.zip_dir,
         "FA_zip_file": zip_ops.zip_file,
diff --git a/automation_file/local/sync_ops.py b/automation_file/local/sync_ops.py
new file mode 100644
index 0000000..32c4976
--- /dev/null
+++ b/automation_file/local/sync_ops.py
@@ -0,0 +1,186 @@
+"""Rsync-style incremental directory synchronisation.
+
+``sync_dir(src, dst)`` mirrors ``src`` into ``dst`` by copying only files
+that are new or changed. Change detection defaults to ``(size, mtime)``,
+which is cheap and correct for the common case; pass ``compare="checksum"``
+to verify contents via SHA-256 when mtime is unreliable (network shares,
+backups restored with reset timestamps, etc.).
+
+Returns a summary dict the caller can log or feed to a notifier::
+
+    {
+        "copied": ["a.txt", "nested/b.txt"],
+        "skipped": ["c.txt"],
+        "deleted": ["old/d.txt"],
+        "errors": [("e.txt", "PermissionError(...)")],
+    }
+
+By default, extra entries in ``dst`` are left alone — pass ``delete=True``
+to prune them. Symlinks in the source tree are not followed; they are
+re-created as symlinks at the destination so tree-crossing links can't
+blow up the sync into a different subtree.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+from automation_file.core.checksum import file_checksum
+from automation_file.exceptions import DirNotExistsException, FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+_COMPARE_MODES = frozenset({"size_mtime", "checksum"})
+_MTIME_TOLERANCE_SECONDS = 2.0
+
+
+class SyncException(FileAutomationException):
+    """Raised for invalid sync arguments (bad compare mode, missing source)."""
+
+
+def sync_dir(
+    src: str | os.PathLike[str],
+    dst: str | os.PathLike[str],
+    *,
+    compare: str = "size_mtime",
+    delete: bool = False,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Mirror ``src`` into ``dst`` incrementally. See module docstring."""
+    if compare not in _COMPARE_MODES:
+        raise SyncException(f"compare must be one of {sorted(_COMPARE_MODES)}, got {compare!r}")
+    source = Path(src)
+    if not source.is_dir():
+        raise DirNotExistsException(str(source))
+    destination = Path(dst)
+    if not dry_run:
+        destination.mkdir(parents=True, exist_ok=True)
+
+    summary: dict[str, Any] = {
+        "copied": [],
+        "skipped": [],
+        "deleted": [],
+        "errors": [],
+        "dry_run": dry_run,
+    }
+
+    src_entries = _walk_relative(source)
+    for rel in src_entries:
+        _process_source_entry(source, destination, rel, compare, dry_run, summary)
+
+    if delete:
+        _delete_extras(source, destination, src_entries, dry_run, summary)
+
+    file_automation_logger.info(
+        "sync_dir %s -> %s: copied=%d skipped=%d deleted=%d errors=%d (dry_run=%s)",
+        source,
+        destination,
+        len(summary["copied"]),
+        len(summary["skipped"]),
+        len(summary["deleted"]),
+        len(summary["errors"]),
+        dry_run,
+    )
+    return summary
+
+
+def _walk_relative(root: Path) -> list[Path]:
+    """Return every entry under ``root`` as a relative ``Path`` (files + symlinks)."""
+    entries: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        dirnames.sort()
+        base = Path(dirpath)
+        for name in sorted(filenames):
+            entries.append((base / name).relative_to(root))
+    return entries
+
+
+def _process_source_entry(
+    source: Path,
+    destination: Path,
+    rel: Path,
+    compare: str,
+    dry_run: bool,
+    summary: dict[str, Any],
+) -> None:
+    src_path = source / rel
+    dst_path = destination / rel
+    try:
+        if _needs_copy(src_path, dst_path, compare):
+            if not dry_run:
+                dst_path.parent.mkdir(parents=True, exist_ok=True)
+                _copy_one(src_path, dst_path)
+            summary["copied"].append(str(rel).replace("\\", "/"))
+        else:
+            summary["skipped"].append(str(rel).replace("\\", "/"))
+    except (OSError, FileAutomationException) as err:
+        summary["errors"].append((str(rel).replace("\\", "/"), repr(err)))
+        file_automation_logger.warning("sync_dir: %s failed: %r", rel, err)
+
+
+def _needs_copy(src: Path, dst: Path, compare: str) -> bool:
+    if not (dst.exists() or dst.is_symlink()):
+        return True
+    src_is_link = src.is_symlink()
+    dst_is_link = dst.is_symlink()
+    if src_is_link != dst_is_link:
+        return True
+    if src_is_link:
+        return os.readlink(src) != os.readlink(dst)
+    src_stat = src.stat()
+    dst_stat = dst.stat()
+    if src_stat.st_size != dst_stat.st_size:
+        return True
+    if compare == "checksum":
+        return file_checksum(src) != file_checksum(dst)
+    return abs(src_stat.st_mtime - dst_stat.st_mtime) > _MTIME_TOLERANCE_SECONDS
+
+
+def _copy_one(src: Path, dst: Path) -> None:
+    if src.is_symlink():
+        if dst.is_symlink() or dst.exists():
+            dst.unlink()
+        os.symlink(os.readlink(src), dst)
+        return
+    shutil.copy2(src, dst)
+
+
+def _delete_extras(
+    source: Path,
+    destination: Path,
+    src_entries: list[Path],
+    dry_run: bool,
+    summary: dict[str, Any],
+) -> None:
+    expected = {str(rel).replace("\\", "/") for rel in src_entries}
+    if not destination.exists():
+        return
+    for dirpath, _dirnames, filenames in os.walk(destination, followlinks=False):
+        base = Path(dirpath)
+        for name in filenames:
+            rel = (base / name).relative_to(destination)
+            rel_str = str(rel).replace("\\", "/")
+            if rel_str in expected:
+                continue
+            target = base / name
+            try:
+                if not dry_run:
+                    target.unlink()
+                summary["deleted"].append(rel_str)
+            except OSError as err:
+                summary["errors"].append((rel_str, repr(err)))
+                file_automation_logger.warning("sync_dir: delete %s failed: %r", rel, err)
+    if not dry_run:
+        _prune_empty_dirs(destination)
+
+
+def _prune_empty_dirs(root: Path) -> None:
+    for dirpath, dirnames, filenames in os.walk(root, topdown=False, followlinks=False):
+        if dirpath == str(root):
+            continue
+        if not dirnames and not filenames:
+            with contextlib.suppress(OSError):
+                Path(dirpath).rmdir()
diff --git a/tests/test_sync_ops.py b/tests/test_sync_ops.py
new file mode 100644
index 0000000..5a4798e
--- /dev/null
+++ b/tests/test_sync_ops.py
@@ -0,0 +1,199 @@
+"""Tests for automation_file.local.sync_ops."""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+import pytest
+
+from automation_file.exceptions import DirNotExistsException
+from automation_file.local.sync_ops import SyncException, sync_dir
+
+
+def _touch(path: Path, content: str = "x") -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def test_sync_copies_new_files(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    _touch(src / "a.txt", "one")
+    _touch(src / "nested" / "b.txt", "two")
+
+    result = sync_dir(src, dst)
+
+    assert set(result["copied"]) == {"a.txt", "nested/b.txt"}
+    assert result["skipped"] == []
+    assert (dst / "a.txt").read_text(encoding="utf-8") == "one"
+    assert (dst / "nested" / "b.txt").read_text(encoding="utf-8") == "two"
+
+
+def test_sync_skips_unchanged_files(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    _touch(src / "a.txt", "same")
+
+    sync_dir(src, dst)
+    # mtime tolerance means a second pass is a no-op.
+    result = sync_dir(src, dst)
+    assert result["copied"] == []
+    assert result["skipped"] == ["a.txt"]
+
+
+def test_sync_detects_size_change(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    _touch(src / "a.txt", "short")
+    sync_dir(src, dst)
+
+    _touch(src / "a.txt", "much longer content than before")
+    result = sync_dir(src, dst)
+
+    assert result["copied"] == ["a.txt"]
+    assert (dst / "a.txt").read_text(encoding="utf-8") == "much longer content than before"
+
+
+def test_sync_detects_checksum_change_when_size_matches(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    _touch(src / "a.txt", "aaa")
+    sync_dir(src, dst)
+
+    # Same size, different content, same mtime.
+    (src / "a.txt").write_text("bbb", encoding="utf-8")
+    stat = (dst / "a.txt").stat()
+    os.utime(src / "a.txt", (stat.st_atime, stat.st_mtime))
+
+    size_result = sync_dir(src, dst, compare="size_mtime")
+    assert size_result["copied"] == []
+
+    checksum_result = sync_dir(src, dst, compare="checksum")
+    assert checksum_result["copied"] == ["a.txt"]
+    assert (dst / "a.txt").read_text(encoding="utf-8") == "bbb"
+
+
+def test_sync_rejects_unknown_compare_mode(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    src.mkdir()
+    with pytest.raises(SyncException, match="compare"):
+        sync_dir(src, tmp_path / "dst", compare="bogus")
+
+
+def test_sync_rejects_missing_source(tmp_path: Path) -> None:
+    with pytest.raises(DirNotExistsException):
+        sync_dir(tmp_path / "missing", tmp_path / "dst")
+
+
+def test_sync_delete_removes_extras(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    _touch(src / "a.txt", "keep")
+    _touch(dst / "a.txt", "keep")
+    _touch(dst / "old.txt", "remove")
+    _touch(dst / "nested" / "stale.txt", "remove")
+
+    result = sync_dir(src, dst, delete=True)
+
+    assert set(result["deleted"]) == {"old.txt", "nested/stale.txt"}
+    assert not (dst / "old.txt").exists()
+    assert not (dst / "nested" / "stale.txt").exists()
+    # Empty nested dir should be pruned.
+    assert not (dst / "nested").exists()
+
+
+def test_sync_delete_disabled_by_default(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    _touch(src / "a.txt", "keep")
+    _touch(dst / "old.txt", "remove")
+
+    result = sync_dir(src, dst)
+    assert result["deleted"] == []
+    assert (dst / "old.txt").exists()
+
+
+def test_sync_dry_run_makes_no_changes(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    _touch(src / "a.txt", "one")
+    _touch(dst / "extra.txt", "stale")
+
+    result = sync_dir(src, dst, delete=True, dry_run=True)
+
+    assert result["dry_run"] is True
+    assert result["copied"] == ["a.txt"]
+    assert result["deleted"] == ["extra.txt"]
+    assert not (dst / "a.txt").exists()
+    assert (dst / "extra.txt").exists()
+
+
+def test_sync_mtime_tolerance_absorbs_small_drift(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    _touch(src / "a.txt", "same")
+    sync_dir(src, dst)
+
+    # Nudge src's mtime by 1s — inside the 2s tolerance, should still skip.
+    stat = (src / "a.txt").stat()
+    os.utime(src / "a.txt", (stat.st_atime, stat.st_mtime + 1.0))
+    result = sync_dir(src, dst)
+    assert result["copied"] == []
+
+
+def test_sync_fa_action_registered() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    registry = build_default_registry()
+    assert "FA_sync_dir" in registry
+
+
+def test_sync_error_recorded_per_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    _touch(src / "good.txt", "ok")
+    _touch(src / "bad.txt", "will-fail")
+
+    import shutil as _shutil
+
+    original_copy2 = _shutil.copy2
+
+    def _fake_copy2(source: str, target: str, *args: object, **kwargs: object) -> str:
+        if str(source).endswith("bad.txt"):
+            raise OSError("simulated copy failure")
+        return original_copy2(source, target, *args, **kwargs)  # type: ignore[no-any-return]
+
+    monkeypatch.setattr("automation_file.local.sync_ops.shutil.copy2", _fake_copy2)
+
+    result = sync_dir(src, dst)
+    # The good file should have made it; the bad one should be reported.
+    assert "good.txt" in result["copied"]
+    assert any(name == "bad.txt" for name, _err in result["errors"])
+
+
+def test_sync_copies_into_existing_dst(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    dst.mkdir()
+    _touch(dst / "keep.txt", "kept")
+    _touch(src / "new.txt", "fresh")
+
+    result = sync_dir(src, dst)
+
+    assert (dst / "keep.txt").exists()
+    assert (dst / "new.txt").read_text(encoding="utf-8") == "fresh"
+    assert result["copied"] == ["new.txt"]
+
+
+def test_sync_preserves_mtime(tmp_path: Path) -> None:
+    src = tmp_path / "src"
+    dst = tmp_path / "dst"
+    _touch(src / "a.txt", "t")
+    past = time.time() - 10_000
+    os.utime(src / "a.txt", (past, past))
+
+    sync_dir(src, dst)
+
+    assert abs((dst / "a.txt").stat().st_mtime - past) < 2.0

From 0c73f7fc7e84bef10104f62cf81c22c6d00cdc59 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 21:33:37 +0800
Subject: [PATCH 14/38] Add manifest write/verify for directory-tree integrity
 checks

---
 automation_file/__init__.py             |   4 +
 automation_file/core/action_registry.py |   4 +-
 automation_file/core/manifest.py        | 183 ++++++++++++++++++++++++
 tests/test_manifest.py                  | 149 +++++++++++++++++++
 4 files changed, 339 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/core/manifest.py
 create mode 100644 tests/test_manifest.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 898e2ff..c8a312b 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -27,6 +27,7 @@
 )
 from automation_file.core.dag_executor import execute_action_dag
 from automation_file.core.json_store import read_action_json, write_action_json
+from automation_file.core.manifest import ManifestException, verify_manifest, write_manifest
 from automation_file.core.package_loader import PackageLoader
 from automation_file.core.progress import (
     CancellationToken,
@@ -248,6 +249,9 @@ def __getattr__(name: str) -> Any:
     "verify_checksum",
     "ChecksumMismatchException",
     "find_duplicates",
+    "ManifestException",
+    "write_manifest",
+    "verify_manifest",
     # Triggers
     "FileWatcher",
     "TriggerManager",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index f45e07c..f7133e9 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -131,7 +131,7 @@ def _http_commands() -> dict[str, Command]:
 
 
 def _utils_commands() -> dict[str, Command]:
-    from automation_file.core import checksum
+    from automation_file.core import checksum, manifest
     from automation_file.utils import deduplicate, fast_find
 
     return {
@@ -140,6 +140,8 @@ def _utils_commands() -> dict[str, Command]:
         "FA_verify_checksum": checksum.verify_checksum,
         "FA_find_duplicates": deduplicate.find_duplicates,
         "FA_execute_action_dag": _lazy_execute_action_dag,
+        "FA_write_manifest": manifest.write_manifest,
+        "FA_verify_manifest": manifest.verify_manifest,
     }
 
 
diff --git a/automation_file/core/manifest.py b/automation_file/core/manifest.py
new file mode 100644
index 0000000..be409dc
--- /dev/null
+++ b/automation_file/core/manifest.py
@@ -0,0 +1,183 @@
+"""Directory-tree manifests — JSON snapshot of every file's checksum.
+
+A manifest is a simple JSON document recording every file under a root,
+its size, and a streaming digest (SHA-256 by default). Two operations::
+
+    write_manifest(root, manifest_path)  # snapshot now
+    verify_manifest(root, manifest_path) # verify the tree still matches
+
+Use cases: release-artifact verification, backup integrity checks, detecting
+tampering on a sync target, or pre-flight checks before a rename / move.
+
+The document shape is intentionally small and human-readable::
+
+    {
+      "version": 1,
+      "algorithm": "sha256",
+      "root": "/abs/path/at/snapshot/time",
+      "created_at": "2026-04-21T10:15:30+00:00",
+      "files": {
+        "a.txt":            {"size": 3,      "checksum": "..."},
+        "nested/b.txt":     {"size": 1_024,  "checksum": "..."}
+      }
+    }
+
+Paths in the ``files`` mapping are POSIX-style (forward-slash) relative
+paths so the manifest round-trips across Windows and Unix.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from automation_file.core.checksum import file_checksum
+from automation_file.exceptions import DirNotExistsException, FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+_MANIFEST_VERSION = 1
+_DEFAULT_ALGO = "sha256"
+
+
+class ManifestException(FileAutomationException):
+    """Raised for invalid manifest documents or unreadable manifest paths."""
+
+
+def write_manifest(
+    root: str | os.PathLike[str],
+    manifest_path: str | os.PathLike[str],
+    *,
+    algorithm: str = _DEFAULT_ALGO,
+) -> dict[str, Any]:
+    """Write a manifest for every file under ``root``. Returns the manifest dict."""
+    root_path = Path(root)
+    if not root_path.is_dir():
+        raise DirNotExistsException(str(root_path))
+    files: dict[str, dict[str, Any]] = {}
+    for relative in _walk_files(root_path):
+        absolute = root_path / relative
+        files[_posix_rel(relative)] = {
+            "size": absolute.stat().st_size,
+            "checksum": file_checksum(absolute, algorithm=algorithm),
+        }
+    manifest: dict[str, Any] = {
+        "version": _MANIFEST_VERSION,
+        "algorithm": algorithm,
+        "root": str(root_path.resolve()),
+        "created_at": dt.datetime.now(dt.timezone.utc).isoformat(),
+        "files": files,
+    }
+    Path(manifest_path).parent.mkdir(parents=True, exist_ok=True)
+    Path(manifest_path).write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    file_automation_logger.info(
+        "write_manifest: %d files under %s -> %s", len(files), root_path, manifest_path
+    )
+    return manifest
+
+
+def verify_manifest(
+    root: str | os.PathLike[str],
+    manifest_path: str | os.PathLike[str],
+) -> dict[str, Any]:
+    """Verify every file recorded in ``manifest_path`` still matches under ``root``.
+
+    Returns a summary dict::
+
+        {
+            "matched":  ["a.txt"],
+            "missing":  ["gone.txt"],
+            "modified": ["changed.txt"],
+            "extra":    ["new.txt"],    # present under root, not in manifest
+            "ok": False,
+        }
+
+    ``ok`` is True iff ``missing`` and ``modified`` are both empty (extras
+    are reported but do not fail verification — mirror ``sync_dir``'s
+    default non-deleting posture).
+    """
+    root_path = Path(root)
+    if not root_path.is_dir():
+        raise DirNotExistsException(str(root_path))
+    manifest = _load_manifest(manifest_path)
+    algorithm = manifest.get("algorithm", _DEFAULT_ALGO)
+    recorded = manifest.get("files") or {}
+
+    summary: dict[str, Any] = {
+        "matched": [],
+        "missing": [],
+        "modified": [],
+        "extra": [],
+        "ok": False,
+    }
+
+    for rel, meta in recorded.items():
+        _verify_one(root_path, rel, meta, algorithm, summary)
+
+    recorded_keys = set(recorded.keys())
+    for rel_path in _walk_files(root_path):
+        posix = _posix_rel(rel_path)
+        if posix not in recorded_keys:
+            summary["extra"].append(posix)
+
+    summary["ok"] = not summary["missing"] and not summary["modified"]
+    file_automation_logger.info(
+        "verify_manifest: ok=%s matched=%d missing=%d modified=%d extra=%d",
+        summary["ok"],
+        len(summary["matched"]),
+        len(summary["missing"]),
+        len(summary["modified"]),
+        len(summary["extra"]),
+    )
+    return summary
+
+
+def _verify_one(
+    root: Path,
+    relative: str,
+    meta: dict[str, Any],
+    algorithm: str,
+    summary: dict[str, Any],
+) -> None:
+    target = root / relative
+    if not target.is_file():
+        summary["missing"].append(relative)
+        return
+    expected = meta.get("checksum")
+    size = meta.get("size")
+    if isinstance(size, int) and target.stat().st_size != size:
+        summary["modified"].append(relative)
+        return
+    if not isinstance(expected, str) or file_checksum(target, algorithm=algorithm) != expected:
+        summary["modified"].append(relative)
+        return
+    summary["matched"].append(relative)
+
+
+def _load_manifest(path: str | os.PathLike[str]) -> dict[str, Any]:
+    manifest_path = Path(path)
+    if not manifest_path.is_file():
+        raise ManifestException(f"manifest not found: {manifest_path}")
+    try:
+        data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as err:
+        raise ManifestException(f"cannot read manifest {manifest_path}: {err}") from err
+    if not isinstance(data, dict) or "files" not in data:
+        raise ManifestException(f"manifest missing 'files' mapping: {manifest_path}")
+    return data
+
+
+def _walk_files(root: Path) -> list[Path]:
+    entries: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        dirnames.sort()
+        base = Path(dirpath)
+        for name in sorted(filenames):
+            entries.append((base / name).relative_to(root))
+    return entries
+
+
+def _posix_rel(relative: Path) -> str:
+    return str(relative).replace("\\", "/")
diff --git a/tests/test_manifest.py b/tests/test_manifest.py
new file mode 100644
index 0000000..ee5dd1f
--- /dev/null
+++ b/tests/test_manifest.py
@@ -0,0 +1,149 @@
+"""Tests for automation_file.core.manifest."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from automation_file.core.manifest import (
+    ManifestException,
+    verify_manifest,
+    write_manifest,
+)
+from automation_file.exceptions import DirNotExistsException
+
+
+def _touch(path: Path, content: str = "x") -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def test_write_and_verify_round_trip(tmp_path: Path) -> None:
+    root = tmp_path / "tree"
+    manifest_path = tmp_path / "manifest.json"
+    _touch(root / "a.txt", "one")
+    _touch(root / "nested" / "b.txt", "two")
+
+    manifest = write_manifest(root, manifest_path)
+    assert manifest["version"] == 1
+    assert manifest["algorithm"] == "sha256"
+    assert set(manifest["files"].keys()) == {"a.txt", "nested/b.txt"}
+    assert manifest["files"]["a.txt"]["size"] == 3
+
+    result = verify_manifest(root, manifest_path)
+    assert result["ok"] is True
+    assert set(result["matched"]) == {"a.txt", "nested/b.txt"}
+    assert result["missing"] == []
+    assert result["modified"] == []
+
+
+def test_verify_detects_modified_file(tmp_path: Path) -> None:
+    root = tmp_path / "tree"
+    manifest_path = tmp_path / "m.json"
+    _touch(root / "a.txt", "original")
+    write_manifest(root, manifest_path)
+
+    (root / "a.txt").write_text("tampered", encoding="utf-8")
+
+    result = verify_manifest(root, manifest_path)
+    assert result["ok"] is False
+    assert result["modified"] == ["a.txt"]
+
+
+def test_verify_detects_missing_file(tmp_path: Path) -> None:
+    root = tmp_path / "tree"
+    manifest_path = tmp_path / "m.json"
+    _touch(root / "gone.txt", "bye")
+    write_manifest(root, manifest_path)
+
+    (root / "gone.txt").unlink()
+
+    result = verify_manifest(root, manifest_path)
+    assert result["ok"] is False
+    assert result["missing"] == ["gone.txt"]
+
+
+def test_verify_reports_extras_without_failing(tmp_path: Path) -> None:
+    root = tmp_path / "tree"
+    manifest_path = tmp_path / "m.json"
+    _touch(root / "a.txt", "one")
+    write_manifest(root, manifest_path)
+
+    _touch(root / "unexpected.txt", "extra")
+
+    result = verify_manifest(root, manifest_path)
+    assert result["ok"] is True  # extras do not fail verification
+    assert result["extra"] == ["unexpected.txt"]
+
+
+def test_write_manifest_rejects_missing_root(tmp_path: Path) -> None:
+    with pytest.raises(DirNotExistsException):
+        write_manifest(tmp_path / "missing", tmp_path / "m.json")
+
+
+def test_verify_manifest_rejects_missing_root(tmp_path: Path) -> None:
+    with pytest.raises(DirNotExistsException):
+        verify_manifest(tmp_path / "missing", tmp_path / "m.json")
+
+
+def test_verify_manifest_rejects_missing_manifest(tmp_path: Path) -> None:
+    root = tmp_path / "tree"
+    root.mkdir()
+    with pytest.raises(ManifestException, match="not found"):
+        verify_manifest(root, tmp_path / "no-such-manifest.json")
+
+
+def test_verify_manifest_rejects_bad_json(tmp_path: Path) -> None:
+    root = tmp_path / "tree"
+    root.mkdir()
+    bad = tmp_path / "bad.json"
+    bad.write_text("{not json", encoding="utf-8")
+    with pytest.raises(ManifestException, match="cannot read"):
+        verify_manifest(root, bad)
+
+
+def test_verify_manifest_rejects_malformed_document(tmp_path: Path) -> None:
+    root = tmp_path / "tree"
+    root.mkdir()
+    bad = tmp_path / "bad.json"
+    bad.write_text(json.dumps({"version": 1}), encoding="utf-8")
+    with pytest.raises(ManifestException, match="'files'"):
+        verify_manifest(root, bad)
+
+
+def test_manifest_actions_registered() -> None:
+    from automation_file.core.action_registry import build_default_registry
+
+    registry = build_default_registry()
+    assert "FA_write_manifest" in registry
+    assert "FA_verify_manifest" in registry
+
+
+def test_manifest_custom_algorithm(tmp_path: Path) -> None:
+    root = tmp_path / "tree"
+    manifest_path = tmp_path / "m.json"
+    _touch(root / "a.txt", "data")
+
+    manifest = write_manifest(root, manifest_path, algorithm="md5")
+    assert manifest["algorithm"] == "md5"
+    # md5 digests are 32 hex chars.
+    assert len(manifest["files"]["a.txt"]["checksum"]) == 32
+
+    assert verify_manifest(root, manifest_path)["ok"] is True
+
+
+def test_manifest_size_mismatch_reports_modified(tmp_path: Path) -> None:
+    root = tmp_path / "tree"
+    manifest_path = tmp_path / "m.json"
+    _touch(root / "a.txt", "abc")
+    write_manifest(root, manifest_path)
+
+    # Tamper with size by appending.
+    with (root / "a.txt").open("a", encoding="utf-8") as handle:
+        handle.write("xyz")
+
+    result = verify_manifest(root, manifest_path)
+    assert result["modified"] == ["a.txt"]
+    assert result["ok"] is False

From cec38bde524da54d1827c13d0f456e020b08cffe Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 21:37:33 +0800
Subject: [PATCH 15/38] Add automation_file.toml config + secret provider
 abstraction

---
 automation_file/__init__.py     |  22 ++++
 automation_file/core/config.py  | 202 ++++++++++++++++++++++++++++++++
 automation_file/core/secrets.py | 141 ++++++++++++++++++++++
 dev.toml                        |   3 +-
 requirements.txt                |   3 +-
 stable.toml                     |   3 +-
 tests/test_config.py            | 176 ++++++++++++++++++++++++++++
 tests/test_secrets.py           | 101 ++++++++++++++++
 8 files changed, 648 insertions(+), 3 deletions(-)
 create mode 100644 automation_file/core/config.py
 create mode 100644 automation_file/core/secrets.py
 create mode 100644 tests/test_config.py
 create mode 100644 tests/test_secrets.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index c8a312b..e1bd656 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -25,6 +25,7 @@
     file_checksum,
     verify_checksum,
 )
+from automation_file.core.config import AutomationConfig, ConfigException
 from automation_file.core.dag_executor import execute_action_dag
 from automation_file.core.json_store import read_action_json, write_action_json
 from automation_file.core.manifest import ManifestException, verify_manifest, write_manifest
@@ -42,6 +43,16 @@
 )
 from automation_file.core.quota import Quota
 from automation_file.core.retry import retry_on_transient
+from automation_file.core.secrets import (
+    ChainedSecretProvider,
+    EnvSecretProvider,
+    FileSecretProvider,
+    SecretException,
+    SecretNotFoundException,
+    SecretProvider,
+    default_provider,
+    resolve_secret_refs,
+)
 from automation_file.local.dir_ops import copy_dir, create_dir, remove_dir_tree, rename_dir
 from automation_file.local.file_ops import (
     copy_all_file_to_dir,
@@ -291,6 +302,17 @@ def __getattr__(name: str) -> Any:
     "notification_manager",
     "notify_send",
     "register_notify_ops",
+    # Config / secrets
+    "AutomationConfig",
+    "ConfigException",
+    "ChainedSecretProvider",
+    "EnvSecretProvider",
+    "FileSecretProvider",
+    "SecretException",
+    "SecretNotFoundException",
+    "SecretProvider",
+    "default_provider",
+    "resolve_secret_refs",
     # UI (lazy-loaded)
     "launch_ui",
 ]
diff --git a/automation_file/core/config.py b/automation_file/core/config.py
new file mode 100644
index 0000000..6b2b1f6
--- /dev/null
+++ b/automation_file/core/config.py
@@ -0,0 +1,202 @@
+"""TOML-based configuration for automation_file.
+
+Callers describe notification sinks, secret-provider roots, and scheduler
+defaults in a single ``automation_file.toml`` file. :class:`AutomationConfig`
+loads it, resolves ``${env:…}`` / ``${file:…}`` references via the secret
+provider chain, and exposes helpers to materialise runtime objects (sinks,
+etc.) without the caller poking at the raw dict.
+
+Minimal example::
+
+    [secrets]
+    file_root = "/run/secrets"
+
+    [[notify.sinks]]
+    type = "slack"
+    name = "team-alerts"
+    webhook_url = "${env:SLACK_WEBHOOK}"
+
+    [[notify.sinks]]
+    type = "email"
+    name = "ops-email"
+    host = "smtp.example.com"
+    port = 587
+    sender = "alerts@example.com"
+    recipients = ["ops@example.com"]
+    username = "${env:SMTP_USER}"
+    password = "${file:smtp_password}"
+
+    [defaults]
+    dedup_seconds = 120
+
+Only the sections the caller uses need to appear; everything is optional.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - exercised only on Python 3.10 runners
+    import tomli as tomllib
+
+from automation_file.core.secrets import (
+    ChainedSecretProvider,
+    default_provider,
+    resolve_secret_refs,
+)
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+from automation_file.notify.manager import NotificationManager
+from automation_file.notify.sinks import (
+    EmailSink,
+    NotificationException,
+    NotificationSink,
+    SlackSink,
+    WebhookSink,
+)
+
+
+class ConfigException(FileAutomationException):
+    """Raised when the config file is missing, unparseable, or malformed."""
+
+
+class AutomationConfig:
+    """Parsed, secret-resolved view of an ``automation_file.toml`` document."""
+
+    def __init__(self, data: dict[str, Any], *, source: Path | None = None) -> None:
+        self._data = data
+        self._source = source
+
+    @classmethod
+    def load(
+        cls,
+        path: str | Path,
+        *,
+        provider: ChainedSecretProvider | None = None,
+    ) -> AutomationConfig:
+        """Parse ``path`` as TOML, resolve secret refs, and return the config."""
+        config_path = Path(path)
+        if not config_path.is_file():
+            raise ConfigException(f"config file not found: {config_path}")
+        try:
+            raw = tomllib.loads(config_path.read_text(encoding="utf-8"))
+        except (OSError, tomllib.TOMLDecodeError) as err:
+            raise ConfigException(f"cannot parse {config_path}: {err}") from err
+        secrets_section = raw.get("secrets") or {}
+        file_root = secrets_section.get("file_root")
+        effective_provider = provider or default_provider(file_root)
+        resolved = resolve_secret_refs(raw, effective_provider)
+        file_automation_logger.info("config loaded from %s", config_path)
+        return cls(resolved, source=config_path)
+
+    @property
+    def source(self) -> Path | None:
+        return self._source
+
+    @property
+    def raw(self) -> dict[str, Any]:
+        """Return a shallow copy of the resolved document."""
+        return dict(self._data)
+
+    def section(self, name: str) -> dict[str, Any]:
+        """Return one top-level section as a dict (empty if absent)."""
+        value = self._data.get(name)
+        if value is None:
+            return {}
+        if not isinstance(value, dict):
+            raise ConfigException(f"section {name!r} must be a table, got {type(value).__name__}")
+        return value
+
+    def notification_sinks(self) -> list[NotificationSink]:
+        """Instantiate every sink declared under ``[[notify.sinks]]``."""
+        notify_section = self.section("notify")
+        entries = notify_section.get("sinks") or []
+        if not isinstance(entries, list):
+            raise ConfigException("'notify.sinks' must be an array of tables")
+        sinks: list[NotificationSink] = []
+        for entry in entries:
+            if not isinstance(entry, dict):
+                raise ConfigException("each 'notify.sinks' entry must be a table")
+            sinks.append(_build_sink(entry))
+        return sinks
+
+    def apply_to(self, manager: NotificationManager) -> int:
+        """Register every configured sink into ``manager``. Returns the count.
+
+        Existing registrations are preserved; duplicates by name are replaced
+        (see :meth:`NotificationManager.register`).
+        """
+        count = 0
+        for sink in self.notification_sinks():
+            manager.register(sink)
+            count += 1
+        defaults = self.section("defaults")
+        if "dedup_seconds" in defaults:
+            try:
+                manager.dedup_seconds = float(defaults["dedup_seconds"])
+            except (TypeError, ValueError) as err:
+                raise ConfigException(
+                    f"defaults.dedup_seconds must be a number, got {defaults['dedup_seconds']!r}"
+                ) from err
+        return count
+
+
+def _build_sink(entry: dict[str, Any]) -> NotificationSink:
+    sink_type = entry.get("type")
+    if not isinstance(sink_type, str):
+        raise ConfigException("each sink entry needs a 'type' string")
+    builder = _SINK_BUILDERS.get(sink_type)
+    if builder is None:
+        raise ConfigException(
+            f"unknown sink type {sink_type!r} (expected one of {sorted(_SINK_BUILDERS)})"
+        )
+    try:
+        return builder(entry)
+    except NotificationException:
+        raise
+    except (TypeError, ValueError) as err:
+        raise ConfigException(
+            f"invalid config for sink {entry.get('name') or sink_type!r}: {err}"
+        ) from err
+
+
+def _build_webhook(entry: dict[str, Any]) -> WebhookSink:
+    return WebhookSink(
+        url=entry["url"],
+        name=entry.get("name", "webhook"),
+        timeout=float(entry.get("timeout", 10.0)),
+        extra_headers=entry.get("extra_headers"),
+    )
+
+
+def _build_slack(entry: dict[str, Any]) -> SlackSink:
+    return SlackSink(
+        webhook_url=entry["webhook_url"],
+        name=entry.get("name", "slack"),
+        timeout=float(entry.get("timeout", 10.0)),
+    )
+
+
+def _build_email(entry: dict[str, Any]) -> EmailSink:
+    return EmailSink(
+        host=entry["host"],
+        port=int(entry["port"]),
+        sender=entry["sender"],
+        recipients=list(entry["recipients"]),
+        username=entry.get("username"),
+        password=entry.get("password"),
+        use_tls=bool(entry.get("use_tls", True)),
+        name=entry.get("name", "email"),
+        timeout=float(entry.get("timeout", 10.0)),
+    )
+
+
+_SINK_BUILDERS = {
+    "webhook": _build_webhook,
+    "slack": _build_slack,
+    "email": _build_email,
+}
diff --git a/automation_file/core/secrets.py b/automation_file/core/secrets.py
new file mode 100644
index 0000000..86facc3
--- /dev/null
+++ b/automation_file/core/secrets.py
@@ -0,0 +1,141 @@
+"""Secret provider abstraction.
+
+A secret is a (name -> value) lookup. Three built-in providers compose via
+:class:`ChainedSecretProvider`:
+
+    - :class:`EnvSecretProvider` resolves from ``os.environ``
+    - :class:`FileSecretProvider` resolves from a directory of per-secret files
+      (Docker / K8s secrets layout)
+    - :class:`ChainedSecretProvider` tries a list in order
+
+The purpose is to keep secrets out of the config file itself. Callers
+write references like ``${env:SLACK_WEBHOOK_URL}`` inside
+``automation_file.toml``; :func:`resolve_secret_refs` walks the document
+and substitutes. Missing secrets raise :class:`SecretNotFoundException`
+so a typo in a reference never silently becomes an empty string.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+_SECRET_PATTERN = re.compile(r"\$\{(env|file):([^}]+)\}")
+
+
+class SecretException(FileAutomationException):
+    """Base for secret-provider failures."""
+
+
+class SecretNotFoundException(SecretException):
+    """Raised when a ``${provider:name}`` reference cannot be resolved."""
+
+
+class SecretProvider(ABC):
+    """Contract for a read-only secret lookup."""
+
+    scheme: str
+
+    @abstractmethod
+    def get(self, name: str) -> str | None:
+        """Return the secret's value, or ``None`` if this provider has no entry."""
+
+
+class EnvSecretProvider(SecretProvider):
+    """Read secrets from process environment variables."""
+
+    scheme = "env"
+
+    def get(self, name: str) -> str | None:
+        return os.environ.get(name)
+
+
+class FileSecretProvider(SecretProvider):
+    """Read secrets from ``<root>/<name>`` (e.g., ``/run/secrets/<name>``)."""
+
+    scheme = "file"
+
+    def __init__(self, root: str | os.PathLike[str]) -> None:
+        self._root = Path(root)
+
+    def get(self, name: str) -> str | None:
+        candidate = self._root / name
+        if not candidate.is_file():
+            return None
+        try:
+            return candidate.read_text(encoding="utf-8").rstrip("\r\n")
+        except OSError as err:
+            file_automation_logger.warning("FileSecretProvider: read %s failed: %r", candidate, err)
+            return None
+
+
+class ChainedSecretProvider(SecretProvider):
+    """Try each child provider in order; return the first non-``None`` value.
+
+    Providers are grouped by ``scheme`` — ``${env:X}`` only consults
+    :class:`EnvSecretProvider` children, ``${file:X}`` only consults
+    :class:`FileSecretProvider` children. Unknown schemes raise
+    :class:`SecretNotFoundException` at resolution time.
+    """
+
+    scheme = "*"
+
+    def __init__(self, providers: list[SecretProvider]) -> None:
+        self._providers = list(providers)
+
+    def get(self, name: str) -> str | None:
+        # Default: consult every child regardless of scheme. Callers who
+        # want scheme-scoped lookup should go through resolve_one().
+        for provider in self._providers:
+            value = provider.get(name)
+            if value is not None:
+                return value
+        return None
+
+    def resolve_one(self, scheme: str, name: str) -> str:
+        for provider in self._providers:
+            if provider.scheme not in (scheme, "*"):
+                continue
+            value = provider.get(name)
+            if value is not None:
+                return value
+        raise SecretNotFoundException(f"no secret for ${{{scheme}:{name}}}")
+
+
+def resolve_secret_refs(value: Any, provider: ChainedSecretProvider) -> Any:
+    """Walk ``value`` (dict/list/str) and substitute every ``${scheme:name}``.
+
+    Strings without references are returned unchanged; non-string scalars
+    pass through untouched. Any unresolved reference raises
+    :class:`SecretNotFoundException` — callers should treat this as a hard
+    configuration error rather than continuing with a hole in the config.
+    """
+    if isinstance(value, str):
+        return _resolve_string(value, provider)
+    if isinstance(value, dict):
+        return {key: resolve_secret_refs(item, provider) for key, item in value.items()}
+    if isinstance(value, list):
+        return [resolve_secret_refs(item, provider) for item in value]
+    return value
+
+
+def _resolve_string(text: str, provider: ChainedSecretProvider) -> str:
+    def substitute(match: re.Match[str]) -> str:
+        scheme, name = match.group(1), match.group(2).strip()
+        return provider.resolve_one(scheme, name)
+
+    return _SECRET_PATTERN.sub(substitute, text)
+
+
+def default_provider(file_root: str | os.PathLike[str] | None = None) -> ChainedSecretProvider:
+    """Return an env-first chain, optionally augmented with a file provider."""
+    providers: list[SecretProvider] = [EnvSecretProvider()]
+    if file_root is not None:
+        providers.append(FileSecretProvider(file_root))
+    return ChainedSecretProvider(providers)
diff --git a/dev.toml b/dev.toml
index 3c15e73..acf164d 100644
--- a/dev.toml
+++ b/dev.toml
@@ -24,7 +24,8 @@ dependencies = [
     "dropbox>=11.36.2",
     "paramiko>=3.4.0",
     "PySide6>=6.6.0",
-    "watchdog>=4.0.0"
+    "watchdog>=4.0.0",
+    "tomli>=2.0.1; python_version<\"3.11\""
 ]
 classifiers = [
     "Programming Language :: Python :: 3.10",
diff --git a/requirements.txt b/requirements.txt
index d6b9100..3193d01 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -6,4 +6,5 @@ PySide6
 requests
 protobuf
 tqdm
-watchdog
\ No newline at end of file
+watchdog
+tomli; python_version<"3.11"
\ No newline at end of file
diff --git a/stable.toml b/stable.toml
index 992dcaf..a0951fd 100644
--- a/stable.toml
+++ b/stable.toml
@@ -24,7 +24,8 @@ dependencies = [
     "dropbox>=11.36.2",
     "paramiko>=3.4.0",
     "PySide6>=6.6.0",
-    "watchdog>=4.0.0"
+    "watchdog>=4.0.0",
+    "tomli>=2.0.1; python_version<\"3.11\""
 ]
 classifiers = [
     "Programming Language :: Python :: 3.10",
diff --git a/tests/test_config.py b/tests/test_config.py
new file mode 100644
index 0000000..b5b8fc4
--- /dev/null
+++ b/tests/test_config.py
@@ -0,0 +1,176 @@
+"""Tests for automation_file.core.config."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from automation_file.core.config import AutomationConfig, ConfigException
+from automation_file.notify.manager import NotificationManager
+from automation_file.notify.sinks import EmailSink, SlackSink, WebhookSink
+
+
+def _write_toml(path: Path, body: str) -> None:
+    path.write_text(body, encoding="utf-8")
+
+
+def test_load_rejects_missing_file(tmp_path: Path) -> None:
+    with pytest.raises(ConfigException, match="not found"):
+        AutomationConfig.load(tmp_path / "missing.toml")
+
+
+def test_load_rejects_malformed_toml(tmp_path: Path) -> None:
+    path = tmp_path / "bad.toml"
+    _write_toml(path, "this is = not [[valid\n")
+    with pytest.raises(ConfigException, match="cannot parse"):
+        AutomationConfig.load(path)
+
+
+def test_load_resolves_env_references(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MY_HOOK", "https://example.com/alerts")
+    path = tmp_path / "c.toml"
+    _write_toml(
+        path,
+        """
+        [[notify.sinks]]
+        type = "webhook"
+        name = "team"
+        url = "${env:MY_HOOK}"
+        """,
+    )
+    config = AutomationConfig.load(path)
+    sinks = config.notification_sinks()
+    assert len(sinks) == 1
+    assert isinstance(sinks[0], WebhookSink)
+    assert sinks[0].name == "team"
+    assert sinks[0].url == "https://example.com/alerts"
+
+
+def test_load_builds_slack_and_email(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("SLACK_URL", "https://hooks.slack.com/services/T/B/X")
+    monkeypatch.setenv("SMTP_PW", "pw")
+    path = tmp_path / "c.toml"
+    _write_toml(
+        path,
+        """
+        [[notify.sinks]]
+        type = "slack"
+        webhook_url = "${env:SLACK_URL}"
+
+        [[notify.sinks]]
+        type = "email"
+        name = "ops"
+        host = "smtp.example.com"
+        port = 587
+        sender = "bot@example.com"
+        recipients = ["ops@example.com"]
+        password = "${env:SMTP_PW}"
+        """,
+    )
+    config = AutomationConfig.load(path)
+    sinks = config.notification_sinks()
+    assert len(sinks) == 2
+    assert isinstance(sinks[0], SlackSink)
+    email_sink = sinks[1]
+    assert isinstance(email_sink, EmailSink)
+    assert email_sink.host == "smtp.example.com"
+    assert email_sink.recipients == ["ops@example.com"]
+
+
+def test_apply_to_registers_and_sets_dedup(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("SLACK_URL", "https://hooks.slack.com/services/T/B/X")
+    path = tmp_path / "c.toml"
+    _write_toml(
+        path,
+        """
+        [defaults]
+        dedup_seconds = 120.5
+
+        [[notify.sinks]]
+        type = "slack"
+        name = "team"
+        webhook_url = "${env:SLACK_URL}"
+        """,
+    )
+    config = AutomationConfig.load(path)
+    manager = NotificationManager(dedup_seconds=0.0)
+    count = config.apply_to(manager)
+    assert count == 1
+    assert manager.dedup_seconds == 120.5
+    descriptions = manager.list()
+    assert descriptions[0]["name"] == "team"
+
+
+def test_rejects_unknown_sink_type(tmp_path: Path) -> None:
+    path = tmp_path / "c.toml"
+    _write_toml(
+        path,
+        """
+        [[notify.sinks]]
+        type = "pigeon"
+        name = "carrier"
+        """,
+    )
+    config = AutomationConfig.load(path)
+    with pytest.raises(ConfigException, match="unknown sink type"):
+        config.notification_sinks()
+
+
+def test_rejects_sink_missing_required_field(tmp_path: Path) -> None:
+    path = tmp_path / "c.toml"
+    _write_toml(
+        path,
+        """
+        [[notify.sinks]]
+        type = "webhook"
+        name = "missing-url"
+        """,
+    )
+    config = AutomationConfig.load(path)
+    with pytest.raises((ConfigException, KeyError)):
+        config.notification_sinks()
+
+
+def test_rejects_bad_dedup_value(tmp_path: Path) -> None:
+    path = tmp_path / "c.toml"
+    _write_toml(
+        path,
+        """
+        [defaults]
+        dedup_seconds = "not-a-number"
+        """,
+    )
+    config = AutomationConfig.load(path)
+    manager = NotificationManager(dedup_seconds=0.0)
+    with pytest.raises(ConfigException, match="dedup_seconds"):
+        config.apply_to(manager)
+
+
+def test_empty_config_yields_no_sinks(tmp_path: Path) -> None:
+    path = tmp_path / "c.toml"
+    _write_toml(path, "# nothing configured\n")
+    config = AutomationConfig.load(path)
+    assert config.notification_sinks() == []
+
+
+def test_file_secret_provider_resolved_from_config(tmp_path: Path) -> None:
+    secrets_dir = tmp_path / "secrets"
+    secrets_dir.mkdir()
+    (secrets_dir / "hook").write_text("https://example.com/alerts\n", encoding="utf-8")
+    path = tmp_path / "c.toml"
+    _write_toml(
+        path,
+        f"""
+        [secrets]
+        file_root = "{secrets_dir.as_posix()}"
+
+        [[notify.sinks]]
+        type = "webhook"
+        name = "ops"
+        url = "${{file:hook}}"
+        """,
+    )
+    config = AutomationConfig.load(path)
+    sinks = config.notification_sinks()
+    assert sinks[0].url == "https://example.com/alerts"
diff --git a/tests/test_secrets.py b/tests/test_secrets.py
new file mode 100644
index 0000000..3253ad4
--- /dev/null
+++ b/tests/test_secrets.py
@@ -0,0 +1,101 @@
+"""Tests for automation_file.core.secrets."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from automation_file.core.secrets import (
+    ChainedSecretProvider,
+    EnvSecretProvider,
+    FileSecretProvider,
+    SecretNotFoundException,
+    default_provider,
+    resolve_secret_refs,
+)
+
+
+def test_env_provider_reads_environ(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MY_SECRET", "top-secret")
+    assert EnvSecretProvider().get("MY_SECRET") == "top-secret"
+    assert EnvSecretProvider().get("NO_SUCH_VAR") is None
+
+
+def test_file_provider_reads_file_without_trailing_newline(tmp_path: Path) -> None:
+    (tmp_path / "webhook").write_text("https://example.com/x\n", encoding="utf-8")
+    provider = FileSecretProvider(tmp_path)
+    assert provider.get("webhook") == "https://example.com/x"
+    assert provider.get("missing") is None
+
+
+def test_chain_tries_each_in_order(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("FROM_ENV", "e-value")
+    (tmp_path / "FROM_FILE").write_text("f-value", encoding="utf-8")
+    chain = ChainedSecretProvider([EnvSecretProvider(), FileSecretProvider(tmp_path)])
+    assert chain.resolve_one("env", "FROM_ENV") == "e-value"
+    assert chain.resolve_one("file", "FROM_FILE") == "f-value"
+
+
+def test_chain_scheme_scoped_lookup(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("ONLY_ENV", "from-env")
+    chain = ChainedSecretProvider([EnvSecretProvider(), FileSecretProvider(tmp_path)])
+    # file:ONLY_ENV must not fall through to the env provider.
+    with pytest.raises(SecretNotFoundException):
+        chain.resolve_one("file", "ONLY_ENV")
+
+
+def test_resolve_secret_refs_substitutes_strings(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HOOK", "https://hooks.slack.com/services/T/B/X")
+    chain = default_provider()
+    result = resolve_secret_refs({"url": "${env:HOOK}", "static": "hi"}, chain)
+    assert result == {"url": "https://hooks.slack.com/services/T/B/X", "static": "hi"}
+
+
+def test_resolve_secret_refs_walks_nested_containers(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("U", "me")
+    monkeypatch.setenv("P", "pw")
+    chain = default_provider()
+    result = resolve_secret_refs(
+        {
+            "notify": {
+                "sinks": [
+                    {"username": "${env:U}", "password": "${env:P}", "port": 587},
+                ]
+            }
+        },
+        chain,
+    )
+    assert result["notify"]["sinks"][0]["username"] == "me"
+    assert result["notify"]["sinks"][0]["password"] == "pw"
+    assert result["notify"]["sinks"][0]["port"] == 587
+
+
+def test_resolve_secret_refs_raises_on_missing() -> None:
+    chain = default_provider()
+    with pytest.raises(SecretNotFoundException, match="DOES_NOT_EXIST"):
+        resolve_secret_refs("${env:DOES_NOT_EXIST}", chain)
+
+
+def test_resolve_secret_refs_multiple_in_one_string(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("USER", "alice")
+    monkeypatch.setenv("HOST", "smtp.example.com")
+    chain = default_provider()
+    assert resolve_secret_refs("${env:USER}@${env:HOST}", chain) == "alice@smtp.example.com"
+
+
+def test_resolve_secret_refs_non_string_pass_through() -> None:
+    chain = default_provider()
+    assert resolve_secret_refs(42, chain) == 42
+    assert resolve_secret_refs(None, chain) is None
+    assert resolve_secret_refs(True, chain) is True
+
+
+def test_default_provider_includes_file_root_when_given(tmp_path: Path) -> None:
+    (tmp_path / "smtp_pw").write_text("secret", encoding="utf-8")
+    chain = default_provider(tmp_path)
+    assert chain.resolve_one("file", "smtp_pw") == "secret"

From d5be2d1d04898321239dcc39d8ee1bfeb6ea63d4 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 21:44:19 +0800
Subject: [PATCH 16/38] Document sync, manifests, notifications, and
 config+secrets

---
 README.md                    | 107 ++++++++++++++++++++++++++++++
 README.zh-CN.md              | 102 +++++++++++++++++++++++++++++
 README.zh-TW.md              | 102 +++++++++++++++++++++++++++++
 docs/source/api/core.rst     |   9 +++
 docs/source/api/index.rst    |   1 +
 docs/source/api/local.rst    |   3 +
 docs/source/api/notify.rst   |   8 +++
 docs/source/architecture.rst |  53 +++++++++++++++
 docs/source/usage.rst        | 122 +++++++++++++++++++++++++++++++++++
 9 files changed, 507 insertions(+)
 create mode 100644 docs/source/api/notify.rst

diff --git a/README.md b/README.md
index c1553d3..ecf3e7e 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,10 @@ facade.
 - **Duplicate-file finder** — three-stage size → partial-hash → full-hash pipeline; unique-size files are never hashed (`FA_find_duplicates`)
 - **DAG action executor** — topological scheduling with parallel fan-out and per-branch skip-on-failure (`FA_execute_action_dag`)
 - **Entry-point plugins** — third-party packages register their own `FA_*` actions via `[project.entry-points."automation_file.actions"]`; `build_default_registry()` picks them up automatically
+- **Incremental directory sync** — rsync-style mirror with size+mtime or checksum change detection, optional delete of extras, dry-run (`FA_sync_dir`)
+- **Directory manifests** — JSON snapshot of every file's checksum under a root, with separate missing/modified/extra reporting on verify (`FA_write_manifest`, `FA_verify_manifest`)
+- **Notification sinks** — webhook / Slack / SMTP with a fanout manager that does per-sink error isolation and sliding-window dedup; auto-notify on trigger + scheduler failures (`FA_notify_send`, `FA_notify_list`)
+- **Config file + secret providers** — declare notification sinks / defaults in `automation_file.toml`; `${env:…}` and `${file:…}` references resolve through an Env/File/Chained provider abstraction so secrets stay out of the file itself
 - PySide6 GUI (`python -m automation_file ui`) with a tab per backend, the JSON-action runner, and dedicated tabs for Triggers, Scheduler, and live Progress
 - Rich CLI with one-shot subcommands plus legacy JSON-batch flags
 - Project scaffolding (`ProjectBuilder`) for executor-based automations
@@ -392,6 +396,109 @@ groups = find_duplicates("/data", min_size=1024)
 
 `FA_find_duplicates` runs the same search from JSON.
 
+### Incremental directory sync
+`sync_dir` mirrors `src` into `dst` by copying only files that are new or
+changed. Change detection is `(size, mtime)` by default; pass
+`compare="checksum"` when mtime is unreliable. Extras under `dst` are left
+alone by default — pass `delete=True` to prune them (and `dry_run=True` to
+preview):
+
+```python
+from automation_file import sync_dir
+
+summary = sync_dir("/data/src", "/data/dst", delete=True)
+# summary: {"copied": [...], "skipped": [...], "deleted": [...],
+#           "errors": [...], "dry_run": False}
+```
+
+Symlinks are re-created as symlinks rather than followed, so a link
+pointing outside the tree can't blow up the mirror. JSON action:
+`FA_sync_dir`.
+
+### Directory manifests
+Write a JSON manifest of every file's checksum under a tree and verify the
+tree hasn't changed later:
+
+```python
+from automation_file import write_manifest, verify_manifest
+
+write_manifest("/release/payload", "/release/MANIFEST.json")
+
+# Later…
+result = verify_manifest("/release/payload", "/release/MANIFEST.json")
+if not result["ok"]:
+    raise SystemExit(f"manifest mismatch: {result}")
+```
+
+`result` reports `matched`, `missing`, `modified`, and `extra` lists
+separately. Extras don't fail verification (mirrors `sync_dir`'s
+non-deleting default); `missing` or `modified` do. JSON actions:
+`FA_write_manifest`, `FA_verify_manifest`.
+
+### Notifications
+Push one-off messages or auto-notify on trigger/scheduler failures via
+webhook, Slack, or SMTP:
+
+```python
+from automation_file import (
+    SlackSink, WebhookSink, EmailSink,
+    notification_manager, notify_send,
+)
+
+notification_manager.register(SlackSink("https://hooks.slack.com/services/T/B/X"))
+notify_send("deploy complete", body="rev abc123", level="info")
+```
+
+Every sink implements the same `send(subject, body, level)` contract. The
+fanout `NotificationManager` does per-sink error isolation (one broken
+sink doesn't starve the others), sliding-window dedup so a stuck trigger
+can't flood a channel, and SSRF validation on every webhook/Slack URL.
+Scheduler and trigger dispatchers auto-notify on failure at
+`level="error"` — registering a sink is all that's needed. JSON actions:
+`FA_notify_send`, `FA_notify_list`.
+
+### Config file and secret providers
+Declare sinks and defaults once in `automation_file.toml`. Secret
+references resolve at load time from environment variables or a file root
+(Docker / K8s style):
+
+```toml
+# automation_file.toml
+
+[secrets]
+file_root = "/run/secrets"
+
+[defaults]
+dedup_seconds = 120
+
+[[notify.sinks]]
+type = "slack"
+name = "team-alerts"
+webhook_url = "${env:SLACK_WEBHOOK}"
+
+[[notify.sinks]]
+type = "email"
+name = "ops-email"
+host = "smtp.example.com"
+port = 587
+sender = "alerts@example.com"
+recipients = ["ops@example.com"]
+username = "${env:SMTP_USER}"
+password = "${file:smtp_password}"
+```
+
+```python
+from automation_file import AutomationConfig, notification_manager
+
+config = AutomationConfig.load("automation_file.toml")
+config.apply_to(notification_manager)
+```
+
+Unresolved `${…}` references raise `SecretNotFoundException` rather than
+silently becoming empty strings. Custom provider chains can be built from
+`ChainedSecretProvider` / `EnvSecretProvider` / `FileSecretProvider` and
+passed as `AutomationConfig.load(path, provider=…)`.
+
 ### DAG action executor
 Run actions in dependency order; independent branches fan out across a
 thread pool. Each node is `{"id": ..., "action": [...], "depends_on":
diff --git a/README.zh-CN.md b/README.zh-CN.md
index f832cbb..0fd51a6 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -23,6 +23,10 @@ TCP / HTTP 服务器执行的 JSON 驱动动作。内附 PySide6 GUI，每个功
 - **重复文件查找器** — 三阶段 size → 部分哈希 → 完整哈希管线；大小唯一的文件完全不会被哈希（`FA_find_duplicates`）
 - **DAG 动作执行器** — 按依赖顺序拓扑调度，独立分支并行展开，失败时其后代默认标记为跳过（`FA_execute_action_dag`）
 - **Entry-point 插件** — 第三方包通过 `[project.entry-points."automation_file.actions"]` 注册自定义 `FA_*` 动作；`build_default_registry()` 会自动加载
+- **增量目录同步** — rsync 风格镜像，支持 size+mtime 或 checksum 变更检测，可选删除多余文件，支持干跑（`FA_sync_dir`）
+- **目录 manifest** — 以 JSON 快照记录树下每个文件的校验和，验证时分开报告 missing / modified / extra（`FA_write_manifest`、`FA_verify_manifest`）
+- **通知 sink** — webhook / Slack / SMTP，fanout 管理器做单 sink 错误隔离与滑动窗口去重；trigger + scheduler 失败时自动通知（`FA_notify_send`、`FA_notify_list`）
+- **配置文件 + 密钥提供者** — 在 `automation_file.toml` 声明通知 sink / 默认值；`${env:…}` 与 `${file:…}` 引用通过 Env / File / Chained 提供者抽象解析，让密钥不留在配置文件中
 - PySide6 GUI（`python -m automation_file ui`）每个后端一个页签，含 JSON 动作执行器，另有 Triggers、Scheduler、实时 Progress 专属页签
 - 功能丰富的 CLI，包含一次性子命令与旧式 JSON 批量标志
 - 项目脚手架（`ProjectBuilder`）协助构建以 executor 为核心的自动化项目
@@ -387,6 +391,104 @@ groups = find_duplicates("/data", min_size=1024)
 
 `FA_find_duplicates` 以相同调用提供给 JSON。
 
+### 增量目录同步
+`sync_dir` 以只复制新增或变更文件的方式将 `src` 镜像到 `dst`。变更检测默认
+为 `(size, mtime)`；当 mtime 不可靠时可传入 `compare="checksum"`。`dst`
+下多余的文件默认保留 — 传入 `delete=True` 才会清理（`dry_run=True` 可先
+预览）：
+
+```python
+from automation_file import sync_dir
+
+summary = sync_dir("/data/src", "/data/dst", delete=True)
+# summary: {"copied": [...], "skipped": [...], "deleted": [...],
+#           "errors": [...], "dry_run": False}
+```
+
+Symlink 会以 symlink 形式重建而非被跟随，因此指向树外的链接不会拖垮镜像。
+JSON 动作：`FA_sync_dir`。
+
+### 目录 manifest
+将树下每个文件的校验和写入 JSON manifest，之后再验证树是否变动：
+
+```python
+from automation_file import write_manifest, verify_manifest
+
+write_manifest("/release/payload", "/release/MANIFEST.json")
+
+# 稍后…
+result = verify_manifest("/release/payload", "/release/MANIFEST.json")
+if not result["ok"]:
+    raise SystemExit(f"manifest mismatch: {result}")
+```
+
+`result` 以 `matched`、`missing`、`modified`、`extra` 分别报告列表。
+多余文件（`extra`）不会让验证失败（对齐 `sync_dir` 默认不删除的行为），
+`missing` 与 `modified` 则会。JSON 动作：`FA_write_manifest`、
+`FA_verify_manifest`。
+
+### 通知
+通过 webhook、Slack 或 SMTP 推送一次性消息，或在 trigger / scheduler
+失败时自动通知：
+
+```python
+from automation_file import (
+    SlackSink, WebhookSink, EmailSink,
+    notification_manager, notify_send,
+)
+
+notification_manager.register(SlackSink("https://hooks.slack.com/services/T/B/X"))
+notify_send("deploy complete", body="rev abc123", level="info")
+```
+
+每个 sink 都遵循相同的 `send(subject, body, level)` 合约。Fanout 的
+`NotificationManager` 会做单 sink 错误隔离（一个坏掉的 sink 不会影响
+其他 sink）、滑动窗口去重（避免卡住的 trigger 刷屏），并对每个
+webhook / Slack URL 进行 SSRF 验证。Scheduler 与 trigger 派发器在失败时
+会以 `level="error"` 自动通知 — 只要注册 sink 就能拿到生产环境告警。
+JSON 动作：`FA_notify_send`、`FA_notify_list`。
+
+### 配置文件与密钥提供者
+在 `automation_file.toml` 一次声明 sink 与默认值。密钥引用在加载时由
+环境变量或文件根目录（Docker / K8s 风格）解析：
+
+```toml
+# automation_file.toml
+
+[secrets]
+file_root = "/run/secrets"
+
+[defaults]
+dedup_seconds = 120
+
+[[notify.sinks]]
+type = "slack"
+name = "team-alerts"
+webhook_url = "${env:SLACK_WEBHOOK}"
+
+[[notify.sinks]]
+type = "email"
+name = "ops-email"
+host = "smtp.example.com"
+port = 587
+sender = "alerts@example.com"
+recipients = ["ops@example.com"]
+username = "${env:SMTP_USER}"
+password = "${file:smtp_password}"
+```
+
+```python
+from automation_file import AutomationConfig, notification_manager
+
+config = AutomationConfig.load("automation_file.toml")
+config.apply_to(notification_manager)
+```
+
+未解析的 `${…}` 引用会抛出 `SecretNotFoundException`，而不是默默变成空
+字符串。可组合 `ChainedSecretProvider` / `EnvSecretProvider` /
+`FileSecretProvider` 构建自定义提供者链，并以
+`AutomationConfig.load(path, provider=…)` 传入。
+
 ### DAG 动作执行器
 按依赖顺序执行动作；独立分支通过线程池并行展开。每个节点的形式为
 `{"id": ..., "action": [...], "depends_on": [...]}`：
diff --git a/README.zh-TW.md b/README.zh-TW.md
index 0aaed5f..36cf182 100644
--- a/README.zh-TW.md
+++ b/README.zh-TW.md
@@ -23,6 +23,10 @@ TCP / HTTP 伺服器執行的 JSON 驅動動作。內附 PySide6 GUI，每個功
 - **重複檔案尋找器** — 三階段 size → 部分雜湊 → 完整雜湊管線；大小唯一的檔案完全不會被雜湊（`FA_find_duplicates`）
 - **DAG 動作執行器** — 依相依順序拓撲排程，獨立分支平行展開，失敗時其後代預設標記跳過（`FA_execute_action_dag`）
 - **Entry-point 外掛** — 第三方套件透過 `[project.entry-points."automation_file.actions"]` 註冊自訂 `FA_*` 動作；`build_default_registry()` 會自動載入
+- **增量目錄同步** — rsync 風格鏡像，支援 size+mtime 或 checksum 變更偵測，選擇性刪除多餘檔案，支援乾跑（`FA_sync_dir`）
+- **目錄 manifest** — 以 JSON 快照記錄樹下每個檔案的檢查碼，驗證時分開回報 missing / modified / extra（`FA_write_manifest`、`FA_verify_manifest`）
+- **通知 sink** — webhook / Slack / SMTP，fanout 管理器做個別 sink 錯誤隔離與滑動視窗去重；trigger + scheduler 失敗時自動通知（`FA_notify_send`、`FA_notify_list`）
+- **設定檔 + 秘密提供者** — 在 `automation_file.toml` 宣告通知 sink / 預設值；`${env:…}` 與 `${file:…}` 參考透過 Env / File / Chained 提供者抽象解析，讓秘密不留在檔案裡
 - PySide6 GUI（`python -m automation_file ui`）每個後端一個分頁，含 JSON 動作執行器，另有 Triggers、Scheduler、即時 Progress 專屬分頁
 - 功能豐富的 CLI，包含一次性子指令與舊式 JSON 批次旗標
 - 專案鷹架（`ProjectBuilder`）協助建立以 executor 為核心的自動化專案
@@ -387,6 +391,104 @@ groups = find_duplicates("/data", min_size=1024)
 
 `FA_find_duplicates` 以相同呼叫提供給 JSON。
 
+### 增量目錄同步
+`sync_dir` 以只複製新增或變更檔案的方式將 `src` 鏡像至 `dst`。變更偵測預設
+為 `(size, mtime)`；當 mtime 不可信時可傳入 `compare="checksum"`。`dst`
+下多餘的檔案預設保留 — 傳入 `delete=True` 才會清除（`dry_run=True` 可先
+預覽）：
+
+```python
+from automation_file import sync_dir
+
+summary = sync_dir("/data/src", "/data/dst", delete=True)
+# summary: {"copied": [...], "skipped": [...], "deleted": [...],
+#           "errors": [...], "dry_run": False}
+```
+
+Symlink 會以 symlink 形式重建而非被跟隨，因此指向樹外的連結不會拖垮鏡像。
+JSON 動作：`FA_sync_dir`。
+
+### 目錄 manifest
+將樹下每個檔案的檢查碼寫入 JSON manifest，之後再驗證樹是否變動：
+
+```python
+from automation_file import write_manifest, verify_manifest
+
+write_manifest("/release/payload", "/release/MANIFEST.json")
+
+# 稍後…
+result = verify_manifest("/release/payload", "/release/MANIFEST.json")
+if not result["ok"]:
+    raise SystemExit(f"manifest mismatch: {result}")
+```
+
+`result` 以 `matched`、`missing`、`modified`、`extra` 分別回報清單。
+多餘檔案（`extra`）不會讓驗證失敗（對齊 `sync_dir` 預設不刪除的行為），
+`missing` 與 `modified` 則會。JSON 動作：`FA_write_manifest`、
+`FA_verify_manifest`。
+
+### 通知
+透過 webhook、Slack 或 SMTP 推送一次性訊息，或在 trigger / scheduler
+失敗時自動通知：
+
+```python
+from automation_file import (
+    SlackSink, WebhookSink, EmailSink,
+    notification_manager, notify_send,
+)
+
+notification_manager.register(SlackSink("https://hooks.slack.com/services/T/B/X"))
+notify_send("deploy complete", body="rev abc123", level="info")
+```
+
+每個 sink 都遵循相同的 `send(subject, body, level)` 合約。Fanout 的
+`NotificationManager` 會進行個別 sink 錯誤隔離（一個壞掉的 sink 不會影響
+其他 sink）、滑動視窗去重（避免卡住的 trigger 洗版），以及對每個
+webhook / Slack URL 做 SSRF 驗證。Scheduler 與 trigger 派送器在失敗時
+會以 `level="error"` 自動通知 — 只要註冊 sink 就能取得生產環境告警。
+JSON 動作：`FA_notify_send`、`FA_notify_list`。
+
+### 設定檔與秘密提供者
+在 `automation_file.toml` 一次宣告 sink 與預設值。秘密參考在載入時由
+環境變數或檔案根目錄（Docker / K8s 風格）解析：
+
+```toml
+# automation_file.toml
+
+[secrets]
+file_root = "/run/secrets"
+
+[defaults]
+dedup_seconds = 120
+
+[[notify.sinks]]
+type = "slack"
+name = "team-alerts"
+webhook_url = "${env:SLACK_WEBHOOK}"
+
+[[notify.sinks]]
+type = "email"
+name = "ops-email"
+host = "smtp.example.com"
+port = 587
+sender = "alerts@example.com"
+recipients = ["ops@example.com"]
+username = "${env:SMTP_USER}"
+password = "${file:smtp_password}"
+```
+
+```python
+from automation_file import AutomationConfig, notification_manager
+
+config = AutomationConfig.load("automation_file.toml")
+config.apply_to(notification_manager)
+```
+
+未解析的 `${…}` 參考會拋出 `SecretNotFoundException`，而非默默變成空字串。
+可組合 `ChainedSecretProvider` / `EnvSecretProvider` /
+`FileSecretProvider` 建立自訂提供者鏈，並以
+`AutomationConfig.load(path, provider=…)` 傳入。
+
 ### DAG 動作執行器
 依相依關係執行動作；獨立分支會透過執行緒池平行展開。每個節點形式為
 `{"id": ..., "action": [...], "depends_on": [...]}`：
diff --git a/docs/source/api/core.rst b/docs/source/api/core.rst
index 78fbb88..e115e43 100644
--- a/docs/source/api/core.rst
+++ b/docs/source/api/core.rst
@@ -28,9 +28,18 @@ Core
 .. automodule:: automation_file.core.checksum
    :members:
 
+.. automodule:: automation_file.core.manifest
+   :members:
+
 .. automodule:: automation_file.core.plugins
    :members:
 
+.. automodule:: automation_file.core.config
+   :members:
+
+.. automodule:: automation_file.core.secrets
+   :members:
+
 .. automodule:: automation_file.exceptions
    :members:
 
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index 16c916d..f0014dc 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -10,6 +10,7 @@ API reference
    server
    trigger
    scheduler
+   notify
    progress
    project
    ui
diff --git a/docs/source/api/local.rst b/docs/source/api/local.rst
index 10c5570..dcdb9ed 100644
--- a/docs/source/api/local.rst
+++ b/docs/source/api/local.rst
@@ -10,5 +10,8 @@ Local operations
 .. automodule:: automation_file.local.zip_ops
    :members:
 
+.. automodule:: automation_file.local.sync_ops
+   :members:
+
 .. automodule:: automation_file.local.safe_paths
    :members:
diff --git a/docs/source/api/notify.rst b/docs/source/api/notify.rst
new file mode 100644
index 0000000..066c645
--- /dev/null
+++ b/docs/source/api/notify.rst
@@ -0,0 +1,8 @@
+Notifications
+=============
+
+.. automodule:: automation_file.notify.sinks
+   :members:
+
+.. automodule:: automation_file.notify.manager
+   :members:
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
index 041db3b..cc58f07 100644
--- a/docs/source/architecture.rst
+++ b/docs/source/architecture.rst
@@ -56,11 +56,15 @@ Module layout
    │   ├── retry.py             # @retry_on_transient
    │   ├── quota.py             # Quota(max_bytes, max_seconds)
    │   ├── checksum.py          # file_checksum, verify_checksum
+   │   ├── manifest.py          # write_manifest, verify_manifest
+   │   ├── config.py            # AutomationConfig (TOML loader + secret resolver)
+   │   ├── secrets.py           # Env/File/Chained secret providers
    │   └── progress.py          # CancellationToken, ProgressReporter, progress_registry
    ├── local/
    │   ├── file_ops.py
    │   ├── dir_ops.py
    │   ├── zip_ops.py
+   │   ├── sync_ops.py          # rsync-style incremental sync
    │   └── safe_paths.py        # safe_join + is_within
    ├── remote/
    │   ├── url_validator.py     # SSRF guard
@@ -78,6 +82,9 @@ Module layout
    ├── scheduler/
    │   ├── cron.py              # 5-field cron expression parser
    │   └── manager.py           # Scheduler background thread + ScheduledJob
+   ├── notify/
+   │   ├── sinks.py             # Webhook / Slack / Email sinks
+   │   └── manager.py           # NotificationManager (fanout + dedup + auto-notify hook)
    ├── project/
    │   ├── project_builder.py
    │   └── templates.py
@@ -136,6 +143,13 @@ Reliability utilities
 * :func:`automation_file.utils.deduplicate.find_duplicates` — three-stage
   size → partial-hash → full-hash pipeline; most files never get hashed
   because unique-size buckets are discarded before any digest is read.
+* :func:`automation_file.sync_dir` — incremental directory mirror with
+  ``(size, mtime)`` or checksum-based change detection, optional delete
+  of extras, and a dry-run mode.
+* :func:`automation_file.write_manifest` /
+  :func:`automation_file.verify_manifest` — JSON snapshot of every file
+  digest under a root, for release-artifact verification and tamper
+  detection.
 * :class:`automation_file.core.progress.CancellationToken` and
   :class:`automation_file.core.progress.ProgressReporter` — opt-in per-transfer
   instrumentation. HTTP download and S3 upload/download accept a
@@ -160,6 +174,45 @@ their own dispatch paths:
   every matching job on a short-lived worker thread so a slow action can't
   starve subsequent jobs.
 
+Both dispatchers call
+:func:`automation_file.notify.manager.notify_on_failure` when an action
+list raises :class:`~automation_file.exceptions.FileAutomationException`.
+The helper is a no-op when no sinks are registered, so auto-notification
+is an opt-in side effect of registering any
+:class:`~automation_file.NotificationSink`.
+
+Notifications
+-------------
+
+:mod:`automation_file.notify` ships three concrete sinks
+(:class:`~automation_file.WebhookSink`, :class:`~automation_file.SlackSink`,
+:class:`~automation_file.EmailSink`) behind one
+:class:`~automation_file.NotificationManager` fanout. The manager owns:
+
+* Per-sink error isolation — one broken sink never aborts the others.
+* Sliding-window dedup keyed on ``(subject, body, level)`` so a stuck
+  trigger can't flood a channel.
+* A shared module-level singleton
+  (:data:`~automation_file.notification_manager`) so CLI, GUI, and
+  long-running dispatchers all publish through one state.
+
+Every webhook/Slack URL passes through
+:func:`~automation_file.remote.url_validator.validate_http_url`, blocking
+SSRF targets. Email sinks never expose the password in ``repr()``.
+
+Configuration and secrets
+-------------------------
+
+:class:`automation_file.AutomationConfig` loads an
+``automation_file.toml`` document and exposes helpers to materialise
+sinks / defaults. Secret placeholders (``${env:NAME}`` /
+``${file:NAME}``) resolve at load time through a
+:class:`~automation_file.ChainedSecretProvider` built from
+:class:`~automation_file.EnvSecretProvider` and/or
+:class:`~automation_file.FileSecretProvider`. Unresolved references
+raise :class:`~automation_file.SecretNotFoundException` so a typo never
+silently becomes an empty string.
+
 Security boundaries
 -------------------
 
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
index 1f03b4b..abc8148 100644
--- a/docs/source/usage.rst
+++ b/docs/source/usage.rst
@@ -343,6 +343,128 @@ all, so a tree of millions of files is cheap to scan:
 
 ``FA_find_duplicates`` exposes the same call to JSON action lists.
 
+Incremental directory sync
+--------------------------
+
+:func:`~automation_file.sync_dir` mirrors ``src`` into ``dst`` by copying
+only files that are new or changed. Change detection is ``(size, mtime)``
+by default; pass ``compare="checksum"`` when mtime is unreliable. Extras
+under ``dst`` are left alone by default — pass ``delete=True`` to prune
+them (and ``dry_run=True`` to preview):
+
+.. code-block:: python
+
+   from automation_file import sync_dir
+
+   summary = sync_dir("/data/src", "/data/dst", delete=True)
+   # summary: {"copied": [...], "skipped": [...], "deleted": [...],
+   #           "errors": [...], "dry_run": False}
+
+The JSON-action form is ``FA_sync_dir``. Symlinks are re-created as
+symlinks rather than followed, so a link pointing outside the tree can't
+blow up the mirror.
+
+Directory manifests
+-------------------
+
+Write a JSON manifest of every file under a tree and verify the tree
+hasn't changed later. Useful for release-artifact verification, backup
+integrity checks, and pre-flight checks before moves:
+
+.. code-block:: python
+
+   from automation_file import write_manifest, verify_manifest
+
+   write_manifest("/release/payload", "/release/MANIFEST.json")
+
+   # Later…
+   result = verify_manifest("/release/payload", "/release/MANIFEST.json")
+   if not result["ok"]:
+       raise SystemExit(f"manifest mismatch: {result}")
+
+``result`` reports ``matched``, ``missing``, ``modified``, and ``extra``
+lists separately. Extras do not fail verification (mirror ``sync_dir``'s
+non-deleting default); ``missing`` or ``modified`` do. Both operations
+are exposed to JSON action lists as ``FA_write_manifest`` and
+``FA_verify_manifest``.
+
+Notifications
+-------------
+
+Push one-off messages or auto-notify on trigger/scheduler failures via
+webhook, Slack, or SMTP:
+
+.. code-block:: python
+
+   from automation_file import (
+       SlackSink, WebhookSink, EmailSink,
+       notification_manager, notify_send,
+   )
+
+   notification_manager.register(SlackSink("https://hooks.slack.com/services/T/B/X"))
+   notify_send("deploy complete", body="rev abc123", level="info")
+
+Every sink implements the same ``send(subject, body, level)`` contract;
+the fanout :class:`~automation_file.NotificationManager` handles:
+
+- Per-sink error isolation — one broken sink doesn't starve the others.
+- Sliding-window dedup — identical ``(subject, body, level)`` messages
+  within ``dedup_seconds`` are dropped so a stuck trigger can't flood a
+  channel.
+- SSRF validation on every webhook/Slack URL.
+
+Scheduler and trigger dispatchers auto-notify on failure at
+``level="error"`` — registering a sink is all that's needed to get
+production alerts. The JSON-action forms are ``FA_notify_send`` and
+``FA_notify_list``.
+
+Config file and secret providers
+--------------------------------
+
+Declare notification sinks and defaults once in a TOML file. Secret
+references resolve at load time from environment variables or a file
+root (Docker / K8s style):
+
+.. code-block:: toml
+
+   # automation_file.toml
+
+   [secrets]
+   file_root = "/run/secrets"
+
+   [defaults]
+   dedup_seconds = 120
+
+   [[notify.sinks]]
+   type = "slack"
+   name = "team-alerts"
+   webhook_url = "${env:SLACK_WEBHOOK}"
+
+   [[notify.sinks]]
+   type = "email"
+   name = "ops-email"
+   host = "smtp.example.com"
+   port = 587
+   sender = "alerts@example.com"
+   recipients = ["ops@example.com"]
+   username = "${env:SMTP_USER}"
+   password = "${file:smtp_password}"
+
+.. code-block:: python
+
+   from automation_file import AutomationConfig, notification_manager
+
+   config = AutomationConfig.load("automation_file.toml")
+   config.apply_to(notification_manager)
+
+Unresolved ``${…}`` references raise
+:class:`~automation_file.SecretNotFoundException` rather than silently
+becoming empty strings. Custom provider chains can be built via
+:class:`~automation_file.ChainedSecretProvider` /
+:class:`~automation_file.EnvSecretProvider` /
+:class:`~automation_file.FileSecretProvider` and passed to
+``AutomationConfig.load(path, provider=…)``.
+
 DAG action executor
 -------------------
 

From 99a80193607eaf42ee45185c9a70f74b0c160f69 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:03:29 +0800
Subject: [PATCH 17/38] Add FA_run_shell safe subprocess action

---
 .idea/FileAutomation.iml                |  2 +-
 automation_file/__init__.py             |  3 +
 automation_file/core/action_registry.py |  4 +-
 automation_file/local/shell_ops.py      | 87 +++++++++++++++++++++++++
 tests/test_shell_ops.py                 | 80 +++++++++++++++++++++++
 5 files changed, 174 insertions(+), 2 deletions(-)
 create mode 100644 automation_file/local/shell_ops.py
 create mode 100644 tests/test_shell_ops.py

diff --git a/.idea/FileAutomation.iml b/.idea/FileAutomation.iml
index 673a12b..91f2d42 100644
--- a/.idea/FileAutomation.iml
+++ b/.idea/FileAutomation.iml
@@ -5,7 +5,7 @@
       <excludeFolder url="file://$MODULE_DIR$/.venv" />
       <excludeFolder url="file://$MODULE_DIR$/venv" />
     </content>
-    <orderEntry type="inheritedJdk" />
+    <orderEntry type="jdk" jdkName="Python 3.14 (FileAutomation)" jdkType="Python SDK" />
     <orderEntry type="sourceFolder" forTests="false" />
   </component>
 </module>
\ No newline at end of file
diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index e1bd656..30f7bc8 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -63,6 +63,7 @@
     rename_file,
 )
 from automation_file.local.safe_paths import is_within, safe_join
+from automation_file.local.shell_ops import ShellException, run_shell
 from automation_file.local.sync_ops import SyncException, sync_dir
 from automation_file.local.zip_ops import (
     read_zip_file,
@@ -204,6 +205,8 @@ def __getattr__(name: str) -> Any:
     "rename_dir",
     "sync_dir",
     "SyncException",
+    "run_shell",
+    "ShellException",
     "zip_dir",
     "zip_file",
     "zip_info",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index f7133e9..87392c7 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -66,7 +66,7 @@ def event_dict(self) -> dict[str, Command]:
 
 
 def _local_commands() -> dict[str, Command]:
-    from automation_file.local import dir_ops, file_ops, sync_ops, zip_ops
+    from automation_file.local import dir_ops, file_ops, shell_ops, sync_ops, zip_ops
 
     return {
         # Files
@@ -82,6 +82,8 @@ def _local_commands() -> dict[str, Command]:
         "FA_remove_dir_tree": dir_ops.remove_dir_tree,
         "FA_rename_dir": dir_ops.rename_dir,
         "FA_sync_dir": sync_ops.sync_dir,
+        # Shell
+        "FA_run_shell": shell_ops.run_shell,
         # Zip
         "FA_zip_dir": zip_ops.zip_dir,
         "FA_zip_file": zip_ops.zip_file,
diff --git a/automation_file/local/shell_ops.py b/automation_file/local/shell_ops.py
new file mode 100644
index 0000000..e7e2a2c
--- /dev/null
+++ b/automation_file/local/shell_ops.py
@@ -0,0 +1,87 @@
+"""Safe subprocess execution (Strategy module for the executor).
+
+``run_shell`` is a deliberately narrow wrapper around :mod:`subprocess`:
+
+* ``argv`` must be a non-empty list of strings — never a single string.
+  This eliminates shell-injection through concatenated user input.
+* ``timeout`` is mandatory (default 60 s) so runaway processes cannot hang
+  the executor.
+* ``shell=True`` is never used.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+_DEFAULT_TIMEOUT_SECONDS = 60.0
+
+
+class ShellException(FileAutomationException):
+    """Raised when a shell command fails (non-zero exit, timeout, or bad argv)."""
+
+
+def run_shell(
+    argv: Sequence[str],
+    *,
+    timeout: float = _DEFAULT_TIMEOUT_SECONDS,
+    cwd: str | None = None,
+    env: Mapping[str, str] | None = None,
+    check: bool = True,
+    capture_output: bool = True,
+) -> dict[str, object]:
+    """Run ``argv`` as a subprocess with a hard timeout.
+
+    ``argv`` must be a non-empty list / tuple of strings. Strings are
+    rejected to block shell-injection via concatenated user input.
+
+    Returns ``{"returncode": int, "stdout": str, "stderr": str}`` when
+    ``capture_output=True``; ``stdout``/``stderr`` are empty strings
+    otherwise.
+
+    Raises :class:`ShellException` when ``check=True`` and the process
+    returns a non-zero exit code or times out.
+    """
+    if isinstance(argv, str) or not isinstance(argv, Sequence):
+        raise ShellException("argv must be a list of strings, not a single string")
+    argv_list = list(argv)
+    if not argv_list or not all(isinstance(part, str) for part in argv_list):
+        raise ShellException("argv must be a non-empty list of strings")
+    if timeout <= 0:
+        raise ShellException("timeout must be positive")
+
+    cwd_path = str(Path(cwd)) if cwd else None
+    env_dict = dict(env) if env is not None else None
+
+    try:
+        completed = subprocess.run(
+            argv_list,
+            timeout=timeout,
+            cwd=cwd_path,
+            env=env_dict,
+            capture_output=capture_output,
+            text=True,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as err:
+        file_automation_logger.error("run_shell: timeout after %.1fs: %s", timeout, argv_list[0])
+        raise ShellException(f"timeout after {timeout:.1f}s: {argv_list[0]}") from err
+    except FileNotFoundError as err:
+        raise ShellException(f"executable not found: {argv_list[0]}") from err
+    except OSError as err:
+        raise ShellException(f"subprocess failed: {err!r}") from err
+
+    result: dict[str, object] = {
+        "returncode": completed.returncode,
+        "stdout": completed.stdout or "" if capture_output else "",
+        "stderr": completed.stderr or "" if capture_output else "",
+    }
+    if check and completed.returncode != 0:
+        file_automation_logger.error("run_shell: exit %d: %s", completed.returncode, argv_list[0])
+        raise ShellException(f"exit {completed.returncode}: {argv_list[0]}")
+    file_automation_logger.info("run_shell: %s -> exit %d", argv_list[0], completed.returncode)
+    return result
diff --git a/tests/test_shell_ops.py b/tests/test_shell_ops.py
new file mode 100644
index 0000000..cedeeab
--- /dev/null
+++ b/tests/test_shell_ops.py
@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import sys
+
+import pytest
+
+from automation_file import ShellException, build_default_registry, run_shell
+
+
+def test_run_shell_echoes_stdout() -> None:
+    result = run_shell([sys.executable, "-c", "print('hi')"])
+    assert result["returncode"] == 0
+    assert "hi" in str(result["stdout"])
+
+
+def test_run_shell_rejects_string_argv() -> None:
+    with pytest.raises(ShellException):
+        run_shell("echo hi")  # type: ignore[arg-type]
+
+
+def test_run_shell_rejects_empty_argv() -> None:
+    with pytest.raises(ShellException):
+        run_shell([])
+
+
+def test_run_shell_rejects_non_string_items() -> None:
+    with pytest.raises(ShellException):
+        run_shell([sys.executable, 42])  # type: ignore[list-item]
+
+
+def test_run_shell_raises_on_nonzero_exit_when_check() -> None:
+    with pytest.raises(ShellException):
+        run_shell([sys.executable, "-c", "raise SystemExit(3)"])
+
+
+def test_run_shell_returns_nonzero_when_check_false() -> None:
+    result = run_shell(
+        [sys.executable, "-c", "raise SystemExit(3)"],
+        check=False,
+    )
+    assert result["returncode"] == 3
+
+
+def test_run_shell_times_out() -> None:
+    with pytest.raises(ShellException):
+        run_shell(
+            [sys.executable, "-c", "import time; time.sleep(5)"],
+            timeout=0.5,
+        )
+
+
+def test_run_shell_missing_executable_raises() -> None:
+    with pytest.raises(ShellException):
+        run_shell(["this-binary-definitely-does-not-exist-12345"])
+
+
+def test_run_shell_is_registered() -> None:
+    registry = build_default_registry()
+    assert "FA_run_shell" in registry
+
+
+def test_run_shell_captures_stderr() -> None:
+    result = run_shell(
+        [sys.executable, "-c", "import sys; sys.stderr.write('oops')"],
+    )
+    assert "oops" in str(result["stderr"])
+
+
+def test_run_shell_no_capture_returns_empty_strings() -> None:
+    result = run_shell(
+        [sys.executable, "-c", "print('x')"],
+        capture_output=False,
+    )
+    assert result["stdout"] == ""
+    assert result["stderr"] == ""
+
+
+def test_run_shell_rejects_zero_timeout() -> None:
+    with pytest.raises(ShellException):
+        run_shell([sys.executable, "-c", "pass"], timeout=0)

From b0c3aee1d4b87f8056d0d91a234272f06e4177d0 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:04:46 +0800
Subject: [PATCH 18/38] Add FA_grep text content search

---
 automation_file/__init__.py             |   4 +
 automation_file/core/action_registry.py |   3 +-
 automation_file/utils/grep.py           | 144 ++++++++++++++++++++++++
 tests/test_grep.py                      |  96 ++++++++++++++++
 4 files changed, 246 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/utils/grep.py
 create mode 100644 tests/test_grep.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 30f7bc8..8110595 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -153,6 +153,7 @@
 from automation_file.utils.deduplicate import find_duplicates
 from automation_file.utils.fast_find import fast_find, has_os_index, scandir_find
 from automation_file.utils.file_discovery import get_dir_files_as_list
+from automation_file.utils.grep import GrepException, grep_files, iter_grep
 
 if TYPE_CHECKING:
     from automation_file.ui.launcher import (
@@ -263,6 +264,9 @@ def __getattr__(name: str) -> Any:
     "verify_checksum",
     "ChecksumMismatchException",
     "find_duplicates",
+    "grep_files",
+    "iter_grep",
+    "GrepException",
     "ManifestException",
     "write_manifest",
     "verify_manifest",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 87392c7..a949759 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -134,7 +134,7 @@ def _http_commands() -> dict[str, Command]:
 
 def _utils_commands() -> dict[str, Command]:
     from automation_file.core import checksum, manifest
-    from automation_file.utils import deduplicate, fast_find
+    from automation_file.utils import deduplicate, fast_find, grep
 
     return {
         "FA_fast_find": fast_find.fast_find,
@@ -144,6 +144,7 @@ def _utils_commands() -> dict[str, Command]:
         "FA_execute_action_dag": _lazy_execute_action_dag,
         "FA_write_manifest": manifest.write_manifest,
         "FA_verify_manifest": manifest.verify_manifest,
+        "FA_grep": grep.grep_files,
     }
 
 
diff --git a/automation_file/utils/grep.py b/automation_file/utils/grep.py
new file mode 100644
index 0000000..b769643
--- /dev/null
+++ b/automation_file/utils/grep.py
@@ -0,0 +1,144 @@
+"""Text content search (``FA_grep``).
+
+A streaming grep over a directory tree. Uses ``os.scandir`` for traversal and
+reads files line-by-line so multi-gigabyte logs never land in RAM all at
+once. Pattern is a literal substring by default; pass ``regex=True`` to
+treat it as a :mod:`re` pattern.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+_DEFAULT_MAX_MATCHES = 1000
+_DEFAULT_MAX_LINE_LEN = 4096
+
+
+class GrepException(FileAutomationException):
+    """Raised when :func:`grep_files` receives invalid arguments."""
+
+
+def grep_files(
+    root: str,
+    pattern: str,
+    *,
+    glob: str | None = None,
+    regex: bool = False,
+    ignore_case: bool = False,
+    max_matches: int = _DEFAULT_MAX_MATCHES,
+    max_line_len: int = _DEFAULT_MAX_LINE_LEN,
+) -> list[dict[str, object]]:
+    """Return matches of ``pattern`` under ``root``.
+
+    Each hit is ``{"path": str, "line": int, "text": str}``. Traversal stops
+    after ``max_matches``. Files with glob filter ``glob`` (matched against
+    filename only) are considered; everything else is skipped. Decoding
+    errors are ignored so binary files don't abort the walk.
+    """
+    if not pattern:
+        raise GrepException("pattern must not be empty")
+    if max_matches <= 0:
+        raise GrepException("max_matches must be positive")
+    root_path = Path(root)
+    if not root_path.is_dir():
+        raise GrepException(f"root is not a directory: {root}")
+
+    matcher = _build_matcher(pattern, regex=regex, ignore_case=ignore_case)
+    matches: list[dict[str, object]] = []
+    for path in _walk(root_path, glob):
+        try:
+            _scan_file(path, matcher, matches, max_matches, max_line_len)
+        except OSError as err:
+            file_automation_logger.debug("grep: skip %s: %r", path, err)
+            continue
+        if len(matches) >= max_matches:
+            break
+    return matches
+
+
+def _build_matcher(pattern: str, *, regex: bool, ignore_case: bool):
+    flags = re.IGNORECASE if ignore_case else 0
+    if regex:
+        try:
+            return re.compile(pattern, flags).search
+        except re.error as err:
+            raise GrepException(f"invalid regex: {err}") from err
+    return re.compile(re.escape(pattern), flags).search
+
+
+def _walk(root: Path, glob: str | None) -> Iterator[Path]:
+    stack: list[str] = [str(root)]
+    while stack:
+        current = stack.pop()
+        try:
+            with os.scandir(current) as it:
+                entries = list(it)
+        except OSError as err:
+            file_automation_logger.debug("grep: scandir %s: %r", current, err)
+            continue
+        for entry in entries:
+            if entry.is_dir(follow_symlinks=False):
+                stack.append(entry.path)
+                continue
+            if not entry.is_file(follow_symlinks=False):
+                continue
+            if glob and not fnmatch.fnmatch(entry.name, glob):
+                continue
+            yield Path(entry.path)
+
+
+def _scan_file(
+    path: Path,
+    matcher,
+    matches: list[dict[str, object]],
+    max_matches: int,
+    max_line_len: int,
+) -> None:
+    with path.open("r", encoding="utf-8", errors="ignore") as handle:
+        for lineno, line in enumerate(handle, start=1):
+            if matcher(line) is None:
+                continue
+            text = line.rstrip("\n")
+            if len(text) > max_line_len:
+                text = text[:max_line_len] + "…"
+            matches.append({"path": str(path), "line": lineno, "text": text})
+            if len(matches) >= max_matches:
+                return
+
+
+def iter_grep(
+    root: str,
+    pattern: str,
+    *,
+    glob: str | None = None,
+    regex: bool = False,
+    ignore_case: bool = False,
+    max_line_len: int = _DEFAULT_MAX_LINE_LEN,
+) -> Iterable[dict[str, object]]:
+    """Streaming variant of :func:`grep_files` — yields hits without buffering."""
+    if not pattern:
+        raise GrepException("pattern must not be empty")
+    root_path = Path(root)
+    if not root_path.is_dir():
+        raise GrepException(f"root is not a directory: {root}")
+    matcher = _build_matcher(pattern, regex=regex, ignore_case=ignore_case)
+    for path in _walk(root_path, glob):
+        try:
+            with path.open("r", encoding="utf-8", errors="ignore") as handle:
+                for lineno, line in enumerate(handle, start=1):
+                    if matcher(line) is None:
+                        continue
+                    text = line.rstrip("\n")
+                    if len(text) > max_line_len:
+                        text = text[:max_line_len] + "…"
+                    yield {"path": str(path), "line": lineno, "text": text}
+        except OSError as err:
+            file_automation_logger.debug("grep: skip %s: %r", path, err)
+            continue
diff --git a/tests/test_grep.py b/tests/test_grep.py
new file mode 100644
index 0000000..94442da
--- /dev/null
+++ b/tests/test_grep.py
@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from automation_file import GrepException, build_default_registry, grep_files, iter_grep
+
+
+@pytest.fixture
+def sample_tree(tmp_path: Path) -> Path:
+    (tmp_path / "a.txt").write_text("hello world\nfoo bar\nHELLO AGAIN\n", encoding="utf-8")
+    (tmp_path / "b.log").write_text("nothing to see here\n", encoding="utf-8")
+    sub = tmp_path / "sub"
+    sub.mkdir()
+    (sub / "c.txt").write_text("another hello\n", encoding="utf-8")
+    return tmp_path
+
+
+def test_grep_literal_match(sample_tree: Path) -> None:
+    hits = grep_files(str(sample_tree), "hello")
+    paths = {hit["path"] for hit in hits}
+    assert any(p.endswith("a.txt") for p in paths)
+    assert any(p.endswith("c.txt") for p in paths)
+
+
+def test_grep_case_insensitive(sample_tree: Path) -> None:
+    hits = grep_files(str(sample_tree), "HELLO", ignore_case=True)
+    assert len(hits) == 3
+
+
+def test_grep_case_sensitive_by_default(sample_tree: Path) -> None:
+    hits = grep_files(str(sample_tree), "HELLO")
+    assert len(hits) == 1
+
+
+def test_grep_regex(sample_tree: Path) -> None:
+    hits = grep_files(str(sample_tree), r"fo+ bar", regex=True)
+    assert len(hits) == 1
+
+
+def test_grep_invalid_regex_raises(sample_tree: Path) -> None:
+    with pytest.raises(GrepException):
+        grep_files(str(sample_tree), "(", regex=True)
+
+
+def test_grep_glob_filter(sample_tree: Path) -> None:
+    hits = grep_files(str(sample_tree), "hello", glob="*.log")
+    assert hits == []
+
+
+def test_grep_empty_pattern_raises(sample_tree: Path) -> None:
+    with pytest.raises(GrepException):
+        grep_files(str(sample_tree), "")
+
+
+def test_grep_nonexistent_root(tmp_path: Path) -> None:
+    with pytest.raises(GrepException):
+        grep_files(str(tmp_path / "nope"), "anything")
+
+
+def test_grep_max_matches(sample_tree: Path) -> None:
+    hits = grep_files(str(sample_tree), "hello", ignore_case=True, max_matches=2)
+    assert len(hits) == 2
+
+
+def test_grep_reports_line_numbers(sample_tree: Path) -> None:
+    hits = grep_files(str(sample_tree), "bar")
+    assert hits[0]["line"] == 2
+
+
+def test_iter_grep_streams(sample_tree: Path) -> None:
+    found = 0
+    for _hit in iter_grep(str(sample_tree), "hello", ignore_case=True):
+        found += 1
+        if found >= 2:
+            break
+    assert found == 2
+
+
+def test_grep_registered() -> None:
+    registry = build_default_registry()
+    assert "FA_grep" in registry
+
+
+def test_grep_long_line_truncated(tmp_path: Path) -> None:
+    (tmp_path / "big.txt").write_text("x" * 10000 + " needle\n", encoding="utf-8")
+    hits = grep_files(str(tmp_path), "needle", max_line_len=100)
+    assert "…" in str(hits[0]["text"])
+
+
+def test_grep_binary_safe(tmp_path: Path) -> None:
+    (tmp_path / "bin.dat").write_bytes(b"\x00\x01\x02needle\x00")
+    (tmp_path / "txt.txt").write_text("needle here\n", encoding="utf-8")
+    hits = grep_files(str(tmp_path), "needle")
+    assert len(hits) >= 1

From c524a97242d5b87dffefc257196c31a49e43a059 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:06:02 +0800
Subject: [PATCH 19/38] Add FA_json_get / FA_json_set / FA_json_delete in-place
 JSON editing

---
 automation_file/__init__.py             |  10 ++
 automation_file/core/action_registry.py |   6 +-
 automation_file/local/json_edit.py      | 172 ++++++++++++++++++++++++
 tests/test_json_edit.py                 | 121 +++++++++++++++++
 4 files changed, 308 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/local/json_edit.py
 create mode 100644 tests/test_json_edit.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 8110595..4c7ecf0 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -62,6 +62,12 @@
     remove_file,
     rename_file,
 )
+from automation_file.local.json_edit import (
+    JsonEditException,
+    json_delete,
+    json_get,
+    json_set,
+)
 from automation_file.local.safe_paths import is_within, safe_join
 from automation_file.local.shell_ops import ShellException, run_shell
 from automation_file.local.sync_ops import SyncException, sync_dir
@@ -208,6 +214,10 @@ def __getattr__(name: str) -> Any:
     "SyncException",
     "run_shell",
     "ShellException",
+    "json_get",
+    "json_set",
+    "json_delete",
+    "JsonEditException",
     "zip_dir",
     "zip_file",
     "zip_info",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index a949759..8bab52b 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -66,7 +66,7 @@ def event_dict(self) -> dict[str, Command]:
 
 
 def _local_commands() -> dict[str, Command]:
-    from automation_file.local import dir_ops, file_ops, shell_ops, sync_ops, zip_ops
+    from automation_file.local import dir_ops, file_ops, json_edit, shell_ops, sync_ops, zip_ops
 
     return {
         # Files
@@ -84,6 +84,10 @@ def _local_commands() -> dict[str, Command]:
         "FA_sync_dir": sync_ops.sync_dir,
         # Shell
         "FA_run_shell": shell_ops.run_shell,
+        # JSON edit
+        "FA_json_get": json_edit.json_get,
+        "FA_json_set": json_edit.json_set,
+        "FA_json_delete": json_edit.json_delete,
         # Zip
         "FA_zip_dir": zip_ops.zip_dir,
         "FA_zip_file": zip_ops.zip_file,
diff --git a/automation_file/local/json_edit.py b/automation_file/local/json_edit.py
new file mode 100644
index 0000000..5b4d101
--- /dev/null
+++ b/automation_file/local/json_edit.py
@@ -0,0 +1,172 @@
+"""In-place JSON file editing with dotted-path key access.
+
+Supports ``get`` / ``set`` / ``delete`` operations against any key path
+``a.b.c`` where each segment is a mapping key or a list index (numeric).
+Writes are atomic — the new content lands in a sibling tempfile that is
+``os.replace`` d over the original after ``json.dumps`` succeeds.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from collections.abc import MutableMapping, MutableSequence
+from pathlib import Path
+from typing import Any
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+_MISSING = object()
+
+
+class JsonEditException(FileAutomationException):
+    """Raised when a JSON edit operation cannot be completed."""
+
+
+def json_get(path: str, key_path: str, default: Any = None) -> Any:
+    """Return the value at dotted ``key_path`` in the JSON file, or ``default``."""
+    data = _load(path)
+    result = _walk(data, _split(key_path))
+    return default if result is _MISSING else result
+
+
+def json_set(path: str, key_path: str, value: Any) -> bool:
+    """Set the value at dotted ``key_path``. Creates intermediate dicts."""
+    data = _load(path)
+    segments = _split(key_path)
+    if not segments:
+        raise JsonEditException("key_path must not be empty")
+    _set_in(data, segments, value)
+    _dump(path, data)
+    file_automation_logger.info("json_set: %s %s", path, key_path)
+    return True
+
+
+def json_delete(path: str, key_path: str) -> bool:
+    """Delete the value at dotted ``key_path``. Returns True if a value was removed."""
+    data = _load(path)
+    segments = _split(key_path)
+    if not segments:
+        raise JsonEditException("key_path must not be empty")
+    removed = _delete_in(data, segments)
+    if removed:
+        _dump(path, data)
+        file_automation_logger.info("json_delete: %s %s", path, key_path)
+    return removed
+
+
+def _split(key_path: str) -> list[str]:
+    if not isinstance(key_path, str):
+        raise JsonEditException("key_path must be a string")
+    return [segment for segment in key_path.split(".") if segment != ""]
+
+
+def _load(path: str) -> Any:
+    file_path = Path(path)
+    if not file_path.is_file():
+        raise JsonEditException(f"not a file: {path}")
+    try:
+        return json.loads(file_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as err:
+        raise JsonEditException(f"cannot read JSON: {path}: {err}") from err
+
+
+def _dump(path: str, data: Any) -> None:
+    file_path = Path(path)
+    directory = file_path.parent
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=str(directory),
+            delete=False,
+            suffix=".tmp",
+        ) as handle:
+            json.dump(data, handle, indent=2, ensure_ascii=False)
+            handle.write("\n")
+            tmp_name = handle.name
+    except OSError as err:
+        raise JsonEditException(f"cannot write temp file near {path}: {err}") from err
+    try:
+        os.replace(tmp_name, str(file_path))
+    except OSError as err:
+        Path(tmp_name).unlink(missing_ok=True)
+        raise JsonEditException(f"cannot replace {path}: {err}") from err
+
+
+def _walk(data: Any, segments: list[str]) -> Any:
+    current: Any = data
+    for segment in segments:
+        try:
+            current = _child(current, segment)
+        except (KeyError, IndexError, TypeError):
+            return _MISSING
+    return current
+
+
+def _child(container: Any, segment: str) -> Any:
+    if isinstance(container, MutableMapping):
+        return container[segment]
+    if isinstance(container, MutableSequence) and segment.lstrip("-").isdigit():
+        return container[int(segment)]
+    raise TypeError(f"cannot index {type(container).__name__} by {segment!r}")
+
+
+def _set_in(data: Any, segments: list[str], value: Any) -> None:
+    container = data
+    for segment in segments[:-1]:
+        if isinstance(container, MutableMapping):
+            if segment not in container or not isinstance(
+                container[segment], (MutableMapping, MutableSequence)
+            ):
+                container[segment] = {}
+            container = container[segment]
+        elif isinstance(container, MutableSequence) and segment.lstrip("-").isdigit():
+            container = container[int(segment)]
+        else:
+            raise JsonEditException(f"cannot traverse into {segment!r}")
+    last = segments[-1]
+    if isinstance(container, MutableMapping):
+        container[last] = value
+        return
+    if isinstance(container, MutableSequence) and last.lstrip("-").isdigit():
+        idx = int(last)
+        if -len(container) <= idx < len(container):
+            container[idx] = value
+            return
+        if idx == len(container):
+            container.append(value)
+            return
+        raise JsonEditException(f"list index out of range: {idx}")
+    raise JsonEditException(f"cannot set into {type(container).__name__}")
+
+
+def _delete_in(data: Any, segments: list[str]) -> bool:
+    container = data
+    for segment in segments[:-1]:
+        if isinstance(container, MutableMapping):
+            if segment not in container:
+                return False
+            container = container[segment]
+        elif isinstance(container, MutableSequence) and segment.lstrip("-").isdigit():
+            idx = int(segment)
+            if not -len(container) <= idx < len(container):
+                return False
+            container = container[idx]
+        else:
+            return False
+    last = segments[-1]
+    if isinstance(container, MutableMapping):
+        if last not in container:
+            return False
+        del container[last]
+        return True
+    if isinstance(container, MutableSequence) and last.lstrip("-").isdigit():
+        idx = int(last)
+        if not -len(container) <= idx < len(container):
+            return False
+        del container[idx]
+        return True
+    return False
diff --git a/tests/test_json_edit.py b/tests/test_json_edit.py
new file mode 100644
index 0000000..bd1caf6
--- /dev/null
+++ b/tests/test_json_edit.py
@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from automation_file import (
+    JsonEditException,
+    build_default_registry,
+    json_delete,
+    json_get,
+    json_set,
+)
+
+
+@pytest.fixture
+def sample_json(tmp_path: Path) -> Path:
+    path = tmp_path / "config.json"
+    path.write_text(
+        json.dumps(
+            {"a": {"b": {"c": 1}}, "list": [10, 20, 30], "top": "level"},
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+    return path
+
+
+def test_json_get_nested(sample_json: Path) -> None:
+    assert json_get(str(sample_json), "a.b.c") == 1
+
+
+def test_json_get_missing_returns_default(sample_json: Path) -> None:
+    assert json_get(str(sample_json), "a.b.missing", default=42) == 42
+
+
+def test_json_get_list_index(sample_json: Path) -> None:
+    assert json_get(str(sample_json), "list.1") == 20
+
+
+def test_json_set_nested(sample_json: Path) -> None:
+    assert json_set(str(sample_json), "a.b.c", 99) is True
+    assert json.loads(sample_json.read_text(encoding="utf-8"))["a"]["b"]["c"] == 99
+
+
+def test_json_set_creates_missing_path(sample_json: Path) -> None:
+    json_set(str(sample_json), "x.y.z", "new")
+    data = json.loads(sample_json.read_text(encoding="utf-8"))
+    assert data["x"]["y"]["z"] == "new"
+
+
+def test_json_set_list_index(sample_json: Path) -> None:
+    json_set(str(sample_json), "list.0", 999)
+    data = json.loads(sample_json.read_text(encoding="utf-8"))
+    assert data["list"][0] == 999
+
+
+def test_json_set_list_append_at_len(sample_json: Path) -> None:
+    json_set(str(sample_json), "list.3", 40)
+    data = json.loads(sample_json.read_text(encoding="utf-8"))
+    assert data["list"] == [10, 20, 30, 40]
+
+
+def test_json_set_list_out_of_range(sample_json: Path) -> None:
+    with pytest.raises(JsonEditException):
+        json_set(str(sample_json), "list.99", "x")
+
+
+def test_json_delete(sample_json: Path) -> None:
+    assert json_delete(str(sample_json), "a.b.c") is True
+    data = json.loads(sample_json.read_text(encoding="utf-8"))
+    assert "c" not in data["a"]["b"]
+
+
+def test_json_delete_missing_returns_false(sample_json: Path) -> None:
+    assert json_delete(str(sample_json), "a.missing.x") is False
+
+
+def test_json_delete_list_index(sample_json: Path) -> None:
+    json_delete(str(sample_json), "list.0")
+    data = json.loads(sample_json.read_text(encoding="utf-8"))
+    assert data["list"] == [20, 30]
+
+
+def test_empty_key_path_raises(sample_json: Path) -> None:
+    with pytest.raises(JsonEditException):
+        json_set(str(sample_json), "", "v")
+
+
+def test_nonexistent_file_raises(tmp_path: Path) -> None:
+    with pytest.raises(JsonEditException):
+        json_get(str(tmp_path / "no.json"), "x")
+
+
+def test_malformed_json_raises(tmp_path: Path) -> None:
+    path = tmp_path / "bad.json"
+    path.write_text("{not json", encoding="utf-8")
+    with pytest.raises(JsonEditException):
+        json_get(str(path), "x")
+
+
+def test_registered_actions() -> None:
+    registry = build_default_registry()
+    assert "FA_json_get" in registry
+    assert "FA_json_set" in registry
+    assert "FA_json_delete" in registry
+
+
+def test_atomic_write_preserves_on_failure(
+    sample_json: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    original = sample_json.read_text(encoding="utf-8")
+
+    def broken_replace(*_a: object, **_kw: object) -> None:
+        raise OSError("simulated")
+
+    monkeypatch.setattr("os.replace", broken_replace)
+    with pytest.raises(JsonEditException):
+        json_set(str(sample_json), "a.b.c", 777)
+    assert sample_json.read_text(encoding="utf-8") == original

From 14b15243a122b4b7ee1d05f93daa65caf1df027b Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:07:46 +0800
Subject: [PATCH 20/38] Add FA_create_tar / FA_extract_tar archive support

---
 automation_file/__init__.py             |   4 +
 automation_file/core/action_registry.py |  13 ++-
 automation_file/local/tar_ops.py        | 108 ++++++++++++++++++++++++
 tests/test_tar_ops.py                   |  99 ++++++++++++++++++++++
 4 files changed, 223 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/local/tar_ops.py
 create mode 100644 tests/test_tar_ops.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 4c7ecf0..73c0879 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -71,6 +71,7 @@
 from automation_file.local.safe_paths import is_within, safe_join
 from automation_file.local.shell_ops import ShellException, run_shell
 from automation_file.local.sync_ops import SyncException, sync_dir
+from automation_file.local.tar_ops import TarException, create_tar, extract_tar
 from automation_file.local.zip_ops import (
     read_zip_file,
     set_zip_password,
@@ -212,6 +213,9 @@ def __getattr__(name: str) -> Any:
     "rename_dir",
     "sync_dir",
     "SyncException",
+    "create_tar",
+    "extract_tar",
+    "TarException",
     "run_shell",
     "ShellException",
     "json_get",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 8bab52b..57db4db 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -66,7 +66,15 @@ def event_dict(self) -> dict[str, Command]:
 
 
 def _local_commands() -> dict[str, Command]:
-    from automation_file.local import dir_ops, file_ops, json_edit, shell_ops, sync_ops, zip_ops
+    from automation_file.local import (
+        dir_ops,
+        file_ops,
+        json_edit,
+        shell_ops,
+        sync_ops,
+        tar_ops,
+        zip_ops,
+    )
 
     return {
         # Files
@@ -88,6 +96,9 @@ def _local_commands() -> dict[str, Command]:
         "FA_json_get": json_edit.json_get,
         "FA_json_set": json_edit.json_set,
         "FA_json_delete": json_edit.json_delete,
+        # Tar
+        "FA_create_tar": tar_ops.create_tar,
+        "FA_extract_tar": tar_ops.extract_tar,
         # Zip
         "FA_zip_dir": zip_ops.zip_dir,
         "FA_zip_file": zip_ops.zip_file,
diff --git a/automation_file/local/tar_ops.py b/automation_file/local/tar_ops.py
new file mode 100644
index 0000000..17d6fe8
--- /dev/null
+++ b/automation_file/local/tar_ops.py
@@ -0,0 +1,108 @@
+"""tar / tar.gz / tar.bz2 / tar.xz archive operations.
+
+Both ``create_tar`` and ``extract_tar`` refuse archives / targets that escape
+the intended root using :func:`safe_join`, and ``extract_tar`` additionally
+rejects archive members whose names, symlinks, or hardlinks would write
+outside the target directory.
+"""
+
+from __future__ import annotations
+
+import tarfile
+from pathlib import Path
+from typing import Literal
+
+from automation_file.exceptions import FileAutomationException, PathTraversalException
+from automation_file.local.safe_paths import is_within
+from automation_file.logging_config import file_automation_logger
+
+_WriteMode = Literal["w", "w:gz", "w:bz2", "w:xz"]
+_COMPRESSIONS: dict[str | None, _WriteMode] = {
+    None: "w",
+    "": "w",
+    "none": "w",
+    "gz": "w:gz",
+    "bz2": "w:bz2",
+    "xz": "w:xz",
+}
+
+
+class TarException(FileAutomationException):
+    """Raised when tar creation or extraction fails."""
+
+
+def create_tar(
+    source: str,
+    target: str,
+    *,
+    compression: str | None = "gz",
+) -> str:
+    """Create a tar archive at ``target`` containing ``source``.
+
+    ``compression`` is one of ``None`` / ``"none"`` / ``"gz"`` / ``"bz2"`` /
+    ``"xz"``. The archive member names are relative to ``source`` — the
+    directory itself is the top-level member.
+    """
+    key = (compression or "").lower() if isinstance(compression, str) else None
+    if key not in _COMPRESSIONS:
+        raise TarException(f"unknown compression: {compression!r}")
+    mode = _COMPRESSIONS[key]
+
+    src_path = Path(source)
+    if not src_path.exists():
+        raise TarException(f"source not found: {source}")
+    target_path = Path(target)
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        with tarfile.open(str(target_path), mode) as archive:
+            archive.add(str(src_path), arcname=src_path.name)
+    except (OSError, tarfile.TarError) as err:
+        raise TarException(f"create_tar failed: {err}") from err
+
+    file_automation_logger.info("create_tar: %s -> %s (%s)", source, target, mode)
+    return str(target_path)
+
+
+def extract_tar(source: str, target_dir: str) -> list[str]:
+    """Extract archive ``source`` into ``target_dir``; reject traversal attempts."""
+    src_path = Path(source)
+    if not src_path.is_file():
+        raise TarException(f"archive not found: {source}")
+    dest = Path(target_dir)
+    dest.mkdir(parents=True, exist_ok=True)
+
+    extracted: list[str] = []
+    try:
+        with tarfile.open(str(src_path), "r:*") as archive:
+            _verify_members(archive, dest)
+            for member in archive.getmembers():
+                archive.extract(member, str(dest), filter="data")
+                extracted.append(member.name)
+    except PathTraversalException:
+        raise
+    except (OSError, tarfile.TarError) as err:
+        raise TarException(f"extract_tar failed: {err}") from err
+
+    file_automation_logger.info("extract_tar: %s -> %s (%d)", source, target_dir, len(extracted))
+    return extracted
+
+
+def _verify_members(archive: tarfile.TarFile, dest: Path) -> None:
+    dest_resolved = dest.resolve()
+    for member in archive.getmembers():
+        candidate = (dest_resolved / member.name).resolve()
+        if not is_within(str(dest_resolved), str(candidate)):
+            raise PathTraversalException(f"tar member escapes target: {member.name}")
+        if member.issym() or member.islnk():
+            link = member.linkname
+            link_path = (
+                (dest_resolved / link).resolve()
+                if not Path(link).is_absolute()
+                else Path(link).resolve()
+            )
+            if not is_within(str(dest_resolved), str(link_path)):
+                raise PathTraversalException(
+                    f"tar {('symlink' if member.issym() else 'hardlink')} escapes target: "
+                    f"{member.name} -> {link}"
+                )
diff --git a/tests/test_tar_ops.py b/tests/test_tar_ops.py
new file mode 100644
index 0000000..ec76159
--- /dev/null
+++ b/tests/test_tar_ops.py
@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import tarfile
+from pathlib import Path
+
+import pytest
+
+from automation_file import (
+    TarException,
+    build_default_registry,
+    create_tar,
+    extract_tar,
+)
+from automation_file.exceptions import PathTraversalException
+
+
+@pytest.fixture
+def sample_dir(tmp_path: Path) -> Path:
+    src = tmp_path / "src"
+    src.mkdir()
+    (src / "a.txt").write_text("hello\n", encoding="utf-8")
+    (src / "sub").mkdir()
+    (src / "sub" / "b.txt").write_text("world\n", encoding="utf-8")
+    return src
+
+
+def test_create_and_extract_gz(sample_dir: Path, tmp_path: Path) -> None:
+    archive = tmp_path / "out.tar.gz"
+    create_tar(str(sample_dir), str(archive))
+    assert archive.is_file()
+
+    dest = tmp_path / "dest"
+    members = extract_tar(str(archive), str(dest))
+    assert members  # non-empty
+    assert (dest / sample_dir.name / "a.txt").read_text(encoding="utf-8") == "hello\n"
+    assert (dest / sample_dir.name / "sub" / "b.txt").read_text(encoding="utf-8") == "world\n"
+
+
+def test_create_uncompressed(sample_dir: Path, tmp_path: Path) -> None:
+    archive = tmp_path / "plain.tar"
+    create_tar(str(sample_dir), str(archive), compression=None)
+    with tarfile.open(str(archive), "r") as tf:
+        assert any(name.endswith("a.txt") for name in tf.getnames())
+
+
+def test_create_bz2(sample_dir: Path, tmp_path: Path) -> None:
+    archive = tmp_path / "out.tar.bz2"
+    create_tar(str(sample_dir), str(archive), compression="bz2")
+    assert archive.is_file()
+
+
+def test_create_xz(sample_dir: Path, tmp_path: Path) -> None:
+    archive = tmp_path / "out.tar.xz"
+    create_tar(str(sample_dir), str(archive), compression="xz")
+    assert archive.is_file()
+
+
+def test_unknown_compression_raises(sample_dir: Path, tmp_path: Path) -> None:
+    with pytest.raises(TarException):
+        create_tar(str(sample_dir), str(tmp_path / "x.tar"), compression="rar")
+
+
+def test_source_not_found_raises(tmp_path: Path) -> None:
+    with pytest.raises(TarException):
+        create_tar(str(tmp_path / "nope"), str(tmp_path / "out.tar"))
+
+
+def test_extract_missing_archive_raises(tmp_path: Path) -> None:
+    with pytest.raises(TarException):
+        extract_tar(str(tmp_path / "nope.tar.gz"), str(tmp_path / "dest"))
+
+
+def test_extract_rejects_path_traversal(tmp_path: Path) -> None:
+    archive = tmp_path / "evil.tar"
+    with tarfile.open(str(archive), "w") as tf:
+        info = tarfile.TarInfo(name="../escape.txt")
+        info.size = 0
+        tf.addfile(info, None)
+
+    with pytest.raises(PathTraversalException):
+        extract_tar(str(archive), str(tmp_path / "dest"))
+
+
+def test_extract_rejects_absolute_symlink(tmp_path: Path) -> None:
+    archive = tmp_path / "evil.tar"
+    with tarfile.open(str(archive), "w") as tf:
+        info = tarfile.TarInfo(name="link")
+        info.type = tarfile.SYMTYPE
+        info.linkname = "/etc/passwd"
+        tf.addfile(info)
+
+    with pytest.raises(PathTraversalException):
+        extract_tar(str(archive), str(tmp_path / "dest"))
+
+
+def test_tar_actions_registered() -> None:
+    registry = build_default_registry()
+    assert "FA_create_tar" in registry
+    assert "FA_extract_tar" in registry

From 2fc4ea327c546f9a5e0cabc6253c5ddec812cb43 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:09:35 +0800
Subject: [PATCH 21/38] Add FA_rotate_backups retention policy

---
 automation_file/__init__.py             |   3 +
 automation_file/core/action_registry.py |   3 +-
 automation_file/utils/rotate.py         | 158 ++++++++++++++++++++++++
 tests/test_rotate.py                    | 125 +++++++++++++++++++
 4 files changed, 288 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/utils/rotate.py
 create mode 100644 tests/test_rotate.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 73c0879..4eb4c84 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -161,6 +161,7 @@
 from automation_file.utils.fast_find import fast_find, has_os_index, scandir_find
 from automation_file.utils.file_discovery import get_dir_files_as_list
 from automation_file.utils.grep import GrepException, grep_files, iter_grep
+from automation_file.utils.rotate import RotateException, rotate_backups
 
 if TYPE_CHECKING:
     from automation_file.ui.launcher import (
@@ -281,6 +282,8 @@ def __getattr__(name: str) -> Any:
     "grep_files",
     "iter_grep",
     "GrepException",
+    "rotate_backups",
+    "RotateException",
     "ManifestException",
     "write_manifest",
     "verify_manifest",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 57db4db..bab767c 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -149,7 +149,7 @@ def _http_commands() -> dict[str, Command]:
 
 def _utils_commands() -> dict[str, Command]:
     from automation_file.core import checksum, manifest
-    from automation_file.utils import deduplicate, fast_find, grep
+    from automation_file.utils import deduplicate, fast_find, grep, rotate
 
     return {
         "FA_fast_find": fast_find.fast_find,
@@ -160,6 +160,7 @@ def _utils_commands() -> dict[str, Command]:
         "FA_write_manifest": manifest.write_manifest,
         "FA_verify_manifest": manifest.verify_manifest,
         "FA_grep": grep.grep_files,
+        "FA_rotate_backups": rotate.rotate_backups,
     }
 
 
diff --git a/automation_file/utils/rotate.py b/automation_file/utils/rotate.py
new file mode 100644
index 0000000..55f04f6
--- /dev/null
+++ b/automation_file/utils/rotate.py
@@ -0,0 +1,158 @@
+"""Backup retention / rotation.
+
+Group files in a directory by their age bucket (daily / weekly / monthly /
+yearly) and keep the N newest per bucket. Everything that falls outside
+every bucket is deleted.
+
+Files are grouped by their mtime, not by filename — the caller just
+controls *which* files are considered via a glob pattern. Perfect for the
+output of ``FA_zip_dir`` / ``FA_write_manifest`` / ``FA_create_tar``.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from collections.abc import Callable
+from datetime import datetime, timezone
+from pathlib import Path
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+_Keyer = Callable[[float], str]
+
+
+class RotateException(FileAutomationException):
+    """Raised when rotate_backups receives invalid arguments."""
+
+
+def rotate_backups(
+    directory: str,
+    pattern: str = "*",
+    *,
+    keep_daily: int = 7,
+    keep_weekly: int = 4,
+    keep_monthly: int = 12,
+    keep_yearly: int = 0,
+    dry_run: bool = False,
+) -> dict[str, object]:
+    """Keep newest N per bucket under ``directory``; delete the rest.
+
+    Returns ``{"kept": [...], "deleted": [...], "dry_run": bool}``.
+
+    Buckets are assigned by mtime:
+
+    * daily   — one slot per calendar day
+    * weekly  — one slot per ISO week
+    * monthly — one slot per (year, month)
+    * yearly  — one slot per year
+
+    A file is kept if it is the *newest* file in any of the top-N slots of
+    any enabled bucket. ``0`` disables a bucket. No file can appear in
+    both ``kept`` and ``deleted``.
+    """
+    for name, value in (
+        ("keep_daily", keep_daily),
+        ("keep_weekly", keep_weekly),
+        ("keep_monthly", keep_monthly),
+        ("keep_yearly", keep_yearly),
+    ):
+        if value < 0:
+            raise RotateException(f"{name} must be >= 0")
+
+    root = Path(directory)
+    if not root.is_dir():
+        raise RotateException(f"not a directory: {directory}")
+
+    candidates: list[tuple[Path, float]] = []
+    for entry in root.iterdir():
+        if not entry.is_file():
+            continue
+        if not fnmatch.fnmatch(entry.name, pattern):
+            continue
+        candidates.append((entry, entry.stat().st_mtime))
+    candidates.sort(key=lambda item: item[1], reverse=True)
+
+    kept = _select_kept(
+        candidates,
+        keep_daily=keep_daily,
+        keep_weekly=keep_weekly,
+        keep_monthly=keep_monthly,
+        keep_yearly=keep_yearly,
+    )
+    kept_paths = {path for path, _ in kept}
+    deleted: list[str] = []
+    for path, _mtime in candidates:
+        if path in kept_paths:
+            continue
+        deleted.append(str(path))
+        if dry_run:
+            continue
+        try:
+            path.unlink()
+        except OSError as err:
+            file_automation_logger.error("rotate_backups: unlink %s failed: %r", path, err)
+
+    file_automation_logger.info(
+        "rotate_backups: kept=%d deleted=%d dry_run=%s",
+        len(kept_paths),
+        len(deleted),
+        dry_run,
+    )
+    return {
+        "kept": [str(path) for path in kept_paths],
+        "deleted": deleted,
+        "dry_run": dry_run,
+    }
+
+
+def _select_kept(
+    candidates: list[tuple[Path, float]],
+    *,
+    keep_daily: int,
+    keep_weekly: int,
+    keep_monthly: int,
+    keep_yearly: int,
+) -> list[tuple[Path, float]]:
+    buckets: list[tuple[int, _Keyer]] = [
+        (keep_daily, _daily_key),
+        (keep_weekly, _weekly_key),
+        (keep_monthly, _monthly_key),
+        (keep_yearly, _yearly_key),
+    ]
+    kept: dict[Path, float] = {}
+    for keep, key in buckets:
+        if keep <= 0:
+            continue
+        seen: dict[object, Path] = {}
+        for path, mtime in candidates:
+            slot = key(mtime)
+            if slot in seen:
+                continue
+            seen[slot] = path
+            if len(seen) >= keep:
+                break
+        for path in seen.values():
+            kept[path] = path.stat().st_mtime
+    return list(kept.items())
+
+
+def _daily_key(mtime: float) -> str:
+    dt = datetime.fromtimestamp(mtime, tz=timezone.utc)
+    return dt.strftime("%Y-%m-%d")
+
+
+def _weekly_key(mtime: float) -> str:
+    dt = datetime.fromtimestamp(mtime, tz=timezone.utc)
+    year, week, _weekday = dt.isocalendar()
+    return f"{year}-W{week:02d}"
+
+
+def _monthly_key(mtime: float) -> str:
+    dt = datetime.fromtimestamp(mtime, tz=timezone.utc)
+    return dt.strftime("%Y-%m")
+
+
+def _yearly_key(mtime: float) -> str:
+    dt = datetime.fromtimestamp(mtime, tz=timezone.utc)
+    return dt.strftime("%Y")
diff --git a/tests/test_rotate.py b/tests/test_rotate.py
new file mode 100644
index 0000000..afe00f1
--- /dev/null
+++ b/tests/test_rotate.py
@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import os
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+
+from automation_file import RotateException, build_default_registry, rotate_backups
+
+
+def _make_file(path: Path, days_ago: int) -> None:
+    path.write_text("data", encoding="utf-8")
+    when = (datetime.now(tz=timezone.utc) - timedelta(days=days_ago)).timestamp()
+    os.utime(path, (when, when))
+
+
+@pytest.fixture
+def backup_dir(tmp_path: Path) -> Path:
+    # Create 30 daily backups
+    for day in range(30):
+        _make_file(tmp_path / f"backup-{day:02d}.zip", days_ago=day)
+    return tmp_path
+
+
+def test_rotate_keeps_daily(backup_dir: Path) -> None:
+    result = rotate_backups(
+        str(backup_dir),
+        "backup-*.zip",
+        keep_daily=5,
+        keep_weekly=0,
+        keep_monthly=0,
+    )
+    assert len(result["kept"]) == 5
+
+
+def test_rotate_dry_run_deletes_nothing(backup_dir: Path) -> None:
+    result = rotate_backups(
+        str(backup_dir),
+        "backup-*.zip",
+        keep_daily=3,
+        keep_weekly=0,
+        keep_monthly=0,
+        dry_run=True,
+    )
+    assert result["dry_run"] is True
+    # All 30 files still exist
+    assert sum(1 for p in backup_dir.iterdir() if p.is_file()) == 30
+
+
+def test_rotate_deletes_unkept(backup_dir: Path) -> None:
+    rotate_backups(
+        str(backup_dir),
+        "backup-*.zip",
+        keep_daily=5,
+        keep_weekly=0,
+        keep_monthly=0,
+    )
+    # Only 5 remain
+    assert sum(1 for p in backup_dir.iterdir() if p.is_file()) == 5
+
+
+def test_rotate_combines_buckets(backup_dir: Path) -> None:
+    result = rotate_backups(
+        str(backup_dir),
+        "backup-*.zip",
+        keep_daily=3,
+        keep_weekly=2,
+        keep_monthly=0,
+    )
+    # At least 3 daily slots are filled; weekly buckets may overlap the same newest files
+    assert 3 <= len(result["kept"]) <= 5
+
+
+def test_rotate_respects_pattern(tmp_path: Path) -> None:
+    _make_file(tmp_path / "keep.log", 0)
+    _make_file(tmp_path / "ignore.bin", 0)
+    result = rotate_backups(
+        str(tmp_path),
+        "*.log",
+        keep_daily=0,
+        keep_weekly=0,
+        keep_monthly=0,
+        keep_yearly=0,
+    )
+    assert any(p.endswith("keep.log") for p in result["deleted"])
+    assert (tmp_path / "ignore.bin").is_file()
+
+
+def test_rotate_rejects_negative(backup_dir: Path) -> None:
+    with pytest.raises(RotateException):
+        rotate_backups(str(backup_dir), keep_daily=-1)
+
+
+def test_rotate_rejects_non_directory(tmp_path: Path) -> None:
+    with pytest.raises(RotateException):
+        rotate_backups(str(tmp_path / "nope"))
+
+
+def test_rotate_registered() -> None:
+    registry = build_default_registry()
+    assert "FA_rotate_backups" in registry
+
+
+def test_rotate_monthly_bucket(tmp_path: Path) -> None:
+    # 60 daily files across multiple months
+    for day in range(60):
+        _make_file(tmp_path / f"m-{day:02d}.zip", days_ago=day)
+    result = rotate_backups(
+        str(tmp_path),
+        "m-*.zip",
+        keep_daily=0,
+        keep_weekly=0,
+        keep_monthly=2,
+    )
+    assert len(result["kept"]) == 2
+
+
+def test_rotate_skips_subdirectories(tmp_path: Path) -> None:
+    (tmp_path / "sub").mkdir()
+    (tmp_path / "sub" / "inside.zip").write_text("x", encoding="utf-8")
+    _make_file(tmp_path / "top.zip", 0)
+    rotate_backups(str(tmp_path), "*.zip", keep_daily=0, keep_weekly=0, keep_monthly=0)
+    # Subdir remains untouched
+    assert (tmp_path / "sub" / "inside.zip").is_file()

From 76ed07fa6e3cb6a9d39ec17bd3fa01fc84061f94 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:14:19 +0800
Subject: [PATCH 22/38] Add FTP / FTPS backend

---
 automation_file/__init__.py                |  12 ++
 automation_file/core/action_registry.py    |   2 +
 automation_file/remote/ftp/__init__.py     |  40 +++++++
 automation_file/remote/ftp/client.py       |  86 ++++++++++++++
 automation_file/remote/ftp/delete_ops.py   |  18 +++
 automation_file/remote/ftp/download_ops.py |  23 ++++
 automation_file/remote/ftp/list_ops.py     |  18 +++
 automation_file/remote/ftp/upload_ops.py   |  64 ++++++++++
 tests/test_ftp_ops.py                      | 132 +++++++++++++++++++++
 9 files changed, 395 insertions(+)
 create mode 100644 automation_file/remote/ftp/__init__.py
 create mode 100644 automation_file/remote/ftp/client.py
 create mode 100644 automation_file/remote/ftp/delete_ops.py
 create mode 100644 automation_file/remote/ftp/download_ops.py
 create mode 100644 automation_file/remote/ftp/list_ops.py
 create mode 100644 automation_file/remote/ftp/upload_ops.py
 create mode 100644 tests/test_ftp_ops.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 4eb4c84..5e3b508 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -104,6 +104,13 @@
     dropbox_instance,
     register_dropbox_ops,
 )
+from automation_file.remote.ftp import (
+    FTPClient,
+    FTPConnectOptions,
+    FTPException,
+    ftp_instance,
+    register_ftp_ops,
+)
 from automation_file.remote.google_drive.client import GoogleDriveClient, driver_instance
 from automation_file.remote.google_drive.delete_ops import drive_delete_file
 from automation_file.remote.google_drive.download_ops import (
@@ -264,6 +271,11 @@ def __getattr__(name: str) -> Any:
     "SFTPClient",
     "sftp_instance",
     "register_sftp_ops",
+    "FTPClient",
+    "FTPConnectOptions",
+    "FTPException",
+    "ftp_instance",
+    "register_ftp_ops",
     # Server / Project / Utils
     "TCPActionServer",
     "start_autocontrol_socket_server",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index bab767c..e7fc2a7 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -178,6 +178,7 @@ def _lazy_execute_action_dag(
 def _register_cloud_backends(registry: ActionRegistry) -> None:
     from automation_file.remote.azure_blob import register_azure_blob_ops
     from automation_file.remote.dropbox_api import register_dropbox_ops
+    from automation_file.remote.ftp import register_ftp_ops
     from automation_file.remote.s3 import register_s3_ops
     from automation_file.remote.sftp import register_sftp_ops
 
@@ -185,6 +186,7 @@ def _register_cloud_backends(registry: ActionRegistry) -> None:
     register_azure_blob_ops(registry)
     register_dropbox_ops(registry)
     register_sftp_ops(registry)
+    register_ftp_ops(registry)
 
 
 def _register_trigger_ops(registry: ActionRegistry) -> None:
diff --git a/automation_file/remote/ftp/__init__.py b/automation_file/remote/ftp/__init__.py
new file mode 100644
index 0000000..248a5b3
--- /dev/null
+++ b/automation_file/remote/ftp/__init__.py
@@ -0,0 +1,40 @@
+"""FTP / FTPS strategy module.
+
+Actions (``FA_ftp_*``) are registered on the shared default registry
+automatically.
+"""
+
+from __future__ import annotations
+
+from automation_file.core.action_registry import ActionRegistry
+from automation_file.remote.ftp import delete_ops, download_ops, list_ops, upload_ops
+from automation_file.remote.ftp.client import (
+    FTPClient,
+    FTPConnectOptions,
+    FTPException,
+    ftp_instance,
+)
+
+
+def register_ftp_ops(registry: ActionRegistry) -> None:
+    """Register every ``FA_ftp_*`` command into ``registry``."""
+    registry.register_many(
+        {
+            "FA_ftp_later_init": ftp_instance.later_init,
+            "FA_ftp_close": ftp_instance.close,
+            "FA_ftp_upload_file": upload_ops.ftp_upload_file,
+            "FA_ftp_upload_dir": upload_ops.ftp_upload_dir,
+            "FA_ftp_download_file": download_ops.ftp_download_file,
+            "FA_ftp_delete_path": delete_ops.ftp_delete_path,
+            "FA_ftp_list_dir": list_ops.ftp_list_dir,
+        }
+    )
+
+
+__all__ = [
+    "FTPClient",
+    "FTPConnectOptions",
+    "FTPException",
+    "ftp_instance",
+    "register_ftp_ops",
+]
diff --git a/automation_file/remote/ftp/client.py b/automation_file/remote/ftp/client.py
new file mode 100644
index 0000000..142f826
--- /dev/null
+++ b/automation_file/remote/ftp/client.py
@@ -0,0 +1,86 @@
+"""FTP / FTPS client (Singleton Facade over :mod:`ftplib`).
+
+FTPS uses :class:`ftplib.FTP_TLS` with explicit ``AUTH TLS`` after the control
+connection is established. Implicit FTPS (``FTPS`` over a dedicated port with
+TLS from the first byte) is not supported — it's effectively obsolete on
+modern servers.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from dataclasses import dataclass
+from ftplib import FTP, FTP_TLS
+from typing import Any
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+
+class FTPException(FileAutomationException):
+    """Raised when an FTP operation fails."""
+
+
+@dataclass(frozen=True)
+class FTPConnectOptions:
+    host: str
+    username: str = "anonymous"
+    password: str = ""
+    port: int = 21
+    tls: bool = False
+    timeout: float = 30.0
+    passive: bool = True
+
+
+class FTPClient:
+    """Minimal FTP / FTPS session wrapper."""
+
+    def __init__(self) -> None:
+        self._ftp: FTP | None = None
+        self._host: str = ""
+
+    def later_init(self, options: FTPConnectOptions | None = None, **kwargs: Any) -> FTP:
+        """Open an FTP control connection. TLS is negotiated when ``tls=True``."""
+        opts = options if options is not None else FTPConnectOptions(**kwargs)
+        ftp: FTP = FTP_TLS(timeout=opts.timeout) if opts.tls else FTP(timeout=opts.timeout)
+        try:
+            ftp.connect(opts.host, opts.port, timeout=opts.timeout)
+            if opts.tls and isinstance(ftp, FTP_TLS):
+                ftp.auth()
+            ftp.login(user=opts.username, passwd=opts.password)
+            if opts.tls and isinstance(ftp, FTP_TLS):
+                ftp.prot_p()
+            ftp.set_pasv(opts.passive)
+        except OSError as err:
+            with contextlib.suppress(OSError):
+                ftp.close()
+            raise FTPException(f"FTP connect failed: {err}") from err
+        self._ftp = ftp
+        self._host = opts.host
+        file_automation_logger.info(
+            "FTPClient: connected to %s@%s:%d (tls=%s)",
+            opts.username,
+            opts.host,
+            opts.port,
+            opts.tls,
+        )
+        return ftp
+
+    def require_ftp(self) -> FTP:
+        if self._ftp is None:
+            raise FTPException("FTPClient not initialised; call later_init() first")
+        return self._ftp
+
+    def close(self) -> bool:
+        if self._ftp is not None:
+            try:
+                self._ftp.quit()
+            except OSError:
+                with contextlib.suppress(OSError):
+                    self._ftp.close()
+            self._ftp = None
+        file_automation_logger.info("FTPClient: closed")
+        return True
+
+
+ftp_instance: FTPClient = FTPClient()
diff --git a/automation_file/remote/ftp/delete_ops.py b/automation_file/remote/ftp/delete_ops.py
new file mode 100644
index 0000000..cb4d737
--- /dev/null
+++ b/automation_file/remote/ftp/delete_ops.py
@@ -0,0 +1,18 @@
+"""FTP delete operations."""
+
+from __future__ import annotations
+
+from automation_file.logging_config import file_automation_logger
+from automation_file.remote.ftp.client import ftp_instance
+
+
+def ftp_delete_path(remote_path: str) -> bool:
+    """Delete a remote file over FTP / FTPS."""
+    ftp = ftp_instance.require_ftp()
+    try:
+        ftp.delete(remote_path)
+        file_automation_logger.info("ftp_delete_path: %s", remote_path)
+        return True
+    except OSError as error:
+        file_automation_logger.error("ftp_delete_path failed: %r", error)
+        return False
diff --git a/automation_file/remote/ftp/download_ops.py b/automation_file/remote/ftp/download_ops.py
new file mode 100644
index 0000000..dd896d1
--- /dev/null
+++ b/automation_file/remote/ftp/download_ops.py
@@ -0,0 +1,23 @@
+"""FTP download operations."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from automation_file.logging_config import file_automation_logger
+from automation_file.remote.ftp.client import ftp_instance
+
+
+def ftp_download_file(remote_path: str, target_path: str) -> bool:
+    """Download ``remote_path`` to ``target_path`` over FTP / FTPS."""
+    ftp = ftp_instance.require_ftp()
+    target = Path(target_path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with target.open("wb") as handle:
+            ftp.retrbinary(f"RETR {remote_path}", handle.write)
+        file_automation_logger.info("ftp_download_file: %s -> %s", remote_path, target)
+        return True
+    except OSError as error:
+        file_automation_logger.error("ftp_download_file failed: %r", error)
+        return False
diff --git a/automation_file/remote/ftp/list_ops.py b/automation_file/remote/ftp/list_ops.py
new file mode 100644
index 0000000..2cf67ff
--- /dev/null
+++ b/automation_file/remote/ftp/list_ops.py
@@ -0,0 +1,18 @@
+"""FTP listing operations."""
+
+from __future__ import annotations
+
+from automation_file.logging_config import file_automation_logger
+from automation_file.remote.ftp.client import ftp_instance
+
+
+def ftp_list_dir(remote_path: str = ".") -> list[str]:
+    """Return the non-recursive listing of ``remote_path``."""
+    ftp = ftp_instance.require_ftp()
+    try:
+        names = ftp.nlst(remote_path)
+    except OSError as error:
+        file_automation_logger.error("ftp_list_dir failed: %r", error)
+        return []
+    file_automation_logger.info("ftp_list_dir: %s (%d entries)", remote_path, len(names))
+    return list(names)
diff --git a/automation_file/remote/ftp/upload_ops.py b/automation_file/remote/ftp/upload_ops.py
new file mode 100644
index 0000000..bbc8345
--- /dev/null
+++ b/automation_file/remote/ftp/upload_ops.py
@@ -0,0 +1,64 @@
+"""FTP upload operations."""
+
+from __future__ import annotations
+
+import posixpath
+from ftplib import error_perm
+from pathlib import Path
+
+from automation_file.exceptions import FileNotExistsException
+from automation_file.logging_config import file_automation_logger
+from automation_file.remote._upload_tree import walk_and_upload
+from automation_file.remote.ftp.client import ftp_instance
+
+
+def _ensure_remote_dir(ftp, remote_dir: str) -> None:
+    if not remote_dir or remote_dir in (".", "/"):
+        return
+    parts: list[str] = []
+    current = remote_dir
+    while current and current not in (".", "/"):
+        parts.append(current)
+        parent = posixpath.dirname(current)
+        if parent == current:
+            break
+        current = parent
+    for part in reversed(parts):
+        try:
+            ftp.mkd(part)
+        except error_perm:
+            continue
+
+
+def ftp_upload_file(file_path: str, remote_path: str) -> bool:
+    """Upload ``file_path`` to ``remote_path`` over FTP / FTPS."""
+    path = Path(file_path)
+    if not path.is_file():
+        raise FileNotExistsException(str(path))
+    ftp = ftp_instance.require_ftp()
+    try:
+        _ensure_remote_dir(ftp, posixpath.dirname(remote_path))
+        with path.open("rb") as handle:
+            ftp.storbinary(f"STOR {remote_path}", handle)
+        file_automation_logger.info("ftp_upload_file: %s -> %s", path, remote_path)
+        return True
+    except OSError as error:
+        file_automation_logger.error("ftp_upload_file failed: %r", error)
+        return False
+
+
+def ftp_upload_dir(dir_path: str, remote_prefix: str) -> list[str]:
+    """Upload every file under ``dir_path`` to ``remote_prefix``."""
+    result = walk_and_upload(
+        dir_path,
+        remote_prefix,
+        lambda prefix, rel: f"{prefix}/{rel}" if prefix else rel,
+        lambda local, remote: ftp_upload_file(str(local), remote),
+    )
+    file_automation_logger.info(
+        "ftp_upload_dir: %s -> %s (%d files)",
+        result.source,
+        result.prefix,
+        len(result.uploaded),
+    )
+    return result.uploaded
diff --git a/tests/test_ftp_ops.py b/tests/test_ftp_ops.py
new file mode 100644
index 0000000..ce48129
--- /dev/null
+++ b/tests/test_ftp_ops.py
@@ -0,0 +1,132 @@
+"""FTP / FTPS backend tests.
+
+Live FTP servers are outside CI; these tests exercise the registry wiring,
+facade exports, guard clauses, and offline error-path behaviour.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from automation_file import (
+    FTPClient,
+    FTPConnectOptions,
+    FTPException,
+    build_default_registry,
+    ftp_instance,
+    register_ftp_ops,
+)
+from automation_file.core.action_registry import ActionRegistry
+from automation_file.exceptions import FileNotExistsException
+from automation_file.remote.ftp import delete_ops, download_ops, list_ops, upload_ops
+
+
+class _FakeFTP:
+    def __init__(self) -> None:
+        self.stored: list[tuple[str, bytes]] = []
+        self.deleted: list[str] = []
+        self.retrieved: list[str] = []
+        self.dirs: list[str] = []
+        self.listings: dict[str, list[str]] = {".": ["a.txt", "b.txt"]}
+
+    def storbinary(self, cmd: str, fp: Any) -> None:
+        self.stored.append((cmd, fp.read()))
+
+    def retrbinary(self, cmd: str, callback: Any) -> None:
+        self.retrieved.append(cmd)
+        callback(b"payload")
+
+    def delete(self, path: str) -> None:
+        self.deleted.append(path)
+
+    def mkd(self, path: str) -> None:
+        self.dirs.append(path)
+
+    def nlst(self, path: str) -> list[str]:
+        return self.listings.get(path, [])
+
+
+@pytest.fixture
+def fake_ftp(monkeypatch: pytest.MonkeyPatch) -> _FakeFTP:
+    fake = _FakeFTP()
+    monkeypatch.setattr(ftp_instance, "_ftp", fake, raising=False)
+    return fake
+
+
+def test_register_ftp_ops_adds_entries() -> None:
+    registry = ActionRegistry()
+    register_ftp_ops(registry)
+    for name in (
+        "FA_ftp_later_init",
+        "FA_ftp_close",
+        "FA_ftp_upload_file",
+        "FA_ftp_upload_dir",
+        "FA_ftp_download_file",
+        "FA_ftp_delete_path",
+        "FA_ftp_list_dir",
+    ):
+        assert name in registry
+
+
+def test_default_registry_contains_ftp() -> None:
+    registry = build_default_registry()
+    assert "FA_ftp_upload_file" in registry
+    assert "FA_ftp_list_dir" in registry
+
+
+def test_require_ftp_raises_when_not_initialised() -> None:
+    client = FTPClient()
+    with pytest.raises(FTPException):
+        client.require_ftp()
+
+
+def test_connect_options_defaults() -> None:
+    opts = FTPConnectOptions(host="example.org")
+    assert opts.port == 21
+    assert opts.tls is False
+    assert opts.username == "anonymous"
+
+
+def test_upload_file_missing_source_raises(fake_ftp: _FakeFTP, tmp_path: Path) -> None:
+    missing = tmp_path / "nope.txt"
+    with pytest.raises(FileNotExistsException):
+        upload_ops.ftp_upload_file(str(missing), "remote/nope.txt")
+
+
+def test_upload_file_stores_payload(fake_ftp: _FakeFTP, tmp_path: Path) -> None:
+    src = tmp_path / "hello.txt"
+    src.write_bytes(b"hi there")
+    assert upload_ops.ftp_upload_file(str(src), "out/hello.txt") is True
+    assert fake_ftp.stored == [("STOR out/hello.txt", b"hi there")]
+    assert "out" in fake_ftp.dirs
+
+
+def test_upload_dir_uploads_all_files(fake_ftp: _FakeFTP, tmp_path: Path) -> None:
+    (tmp_path / "sub").mkdir()
+    (tmp_path / "a.txt").write_bytes(b"A")
+    (tmp_path / "sub" / "b.txt").write_bytes(b"B")
+    uploaded = upload_ops.ftp_upload_dir(str(tmp_path), "root")
+    assert sorted(uploaded) == ["root/a.txt", "root/sub/b.txt"]
+
+
+def test_download_file_writes_target(fake_ftp: _FakeFTP, tmp_path: Path) -> None:
+    target = tmp_path / "out" / "file.bin"
+    assert download_ops.ftp_download_file("remote/file.bin", str(target)) is True
+    assert target.read_bytes() == b"payload"
+
+
+def test_delete_path_calls_delete(fake_ftp: _FakeFTP) -> None:
+    assert delete_ops.ftp_delete_path("remote/x") is True
+    assert fake_ftp.deleted == ["remote/x"]
+
+
+def test_list_dir_returns_names(fake_ftp: _FakeFTP) -> None:
+    assert list_ops.ftp_list_dir(".") == ["a.txt", "b.txt"]
+
+
+def test_close_on_fresh_client_is_noop() -> None:
+    client = FTPClient()
+    assert client.close() is True

From 58636f56ce10650081871f31a8e4c6a0911bc0bd Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:15:52 +0800
Subject: [PATCH 23/38] Add scheduler job lock to prevent overlap

---
 automation_file/scheduler/manager.py | 76 +++++++++++++++++++++++-----
 tests/test_scheduler.py              | 39 ++++++++++++++
 2 files changed, 102 insertions(+), 13 deletions(-)

diff --git a/automation_file/scheduler/manager.py b/automation_file/scheduler/manager.py
index c040a9c..9444d94 100644
--- a/automation_file/scheduler/manager.py
+++ b/automation_file/scheduler/manager.py
@@ -34,6 +34,9 @@ class ScheduledJob:
     action_list: list[list[Any]]
     last_run: dt.datetime | None = field(default=None)
     runs: int = field(default=0)
+    allow_overlap: bool = field(default=False)
+    running: bool = field(default=False)
+    skipped: int = field(default=0)
 
     def as_dict(self) -> dict[str, Any]:
         return {
@@ -42,6 +45,9 @@ def as_dict(self) -> dict[str, Any]:
             "actions": len(self.action_list),
             "last_run": self.last_run.isoformat() if self.last_run else None,
             "runs": self.runs,
+            "allow_overlap": self.allow_overlap,
+            "running": self.running,
+            "skipped": self.skipped,
         }
 
 
@@ -80,31 +86,65 @@ def _fire_due(self, moment: dt.datetime) -> None:
         for job in due:
             self._dispatch(job, moment)
 
-    @staticmethod
-    def _dispatch(job: ScheduledJob, moment: dt.datetime) -> None:
-        job.last_run = moment
-        job.runs += 1
+    def _dispatch(self, job: ScheduledJob, moment: dt.datetime) -> None:
+        with self._lock:
+            if job.running and not job.allow_overlap:
+                job.skipped += 1
+                file_automation_logger.warning(
+                    "scheduler[%s]: previous run still active — skipping (skipped=%d)",
+                    job.name,
+                    job.skipped,
+                )
+                return
+            job.running = True
+            job.last_run = moment
+            job.runs += 1
+            run_no = job.runs
         file_automation_logger.info(
-            "scheduler[%s]: firing at %s (run #%d)", job.name, moment.isoformat(), job.runs
+            "scheduler[%s]: firing at %s (run #%d)", job.name, moment.isoformat(), run_no
         )
         worker = threading.Thread(
-            target=_safe_execute,
-            args=(job.name, job.action_list),
+            target=self._run_job,
+            args=(job,),
             name=f"fa-scheduler-{job.name}",
             daemon=True,
         )
         worker.start()
 
-    def add(self, name: str, cron_expression: str, action_list: list[list[Any]]) -> dict[str, Any]:
+    def _run_job(self, job: ScheduledJob) -> None:
+        try:
+            _safe_execute(job.name, job.action_list)
+        finally:
+            with self._lock:
+                job.running = False
+
+    def add(
+        self,
+        name: str,
+        cron_expression: str,
+        action_list: list[list[Any]],
+        *,
+        allow_overlap: bool = False,
+    ) -> dict[str, Any]:
         cron = CronExpression.parse(cron_expression)
         with self._lock:
             if name in self._jobs:
                 raise SchedulerException(f"job already registered: {name}")
-            job = ScheduledJob(name=name, cron=cron, action_list=list(action_list))
+            job = ScheduledJob(
+                name=name,
+                cron=cron,
+                action_list=list(action_list),
+                allow_overlap=allow_overlap,
+            )
             self._jobs[name] = job
             snapshot = job.as_dict()
         self._ensure_running()
-        file_automation_logger.info("scheduler: added job %r (cron=%r)", name, cron.source)
+        file_automation_logger.info(
+            "scheduler: added job %r (cron=%r allow_overlap=%s)",
+            name,
+            cron.source,
+            allow_overlap,
+        )
         return snapshot
 
     def remove(self, name: str) -> dict[str, Any]:
@@ -150,9 +190,19 @@ def _safe_execute(job_name: str, action_list: list[list[Any]]) -> None:
 scheduler: Scheduler = Scheduler()
 
 
-def schedule_add(name: str, cron_expression: str, action_list: list[list[Any]]) -> dict[str, Any]:
-    """Register a named job that fires ``action_list`` on ``cron_expression``."""
-    return scheduler.add(name, cron_expression, action_list)
+def schedule_add(
+    name: str,
+    cron_expression: str,
+    action_list: list[list[Any]],
+    *,
+    allow_overlap: bool = False,
+) -> dict[str, Any]:
+    """Register a named job that fires ``action_list`` on ``cron_expression``.
+
+    When ``allow_overlap`` is False (the default), a tick that fires while a
+    previous run is still active is skipped and counted in ``skipped``.
+    """
+    return scheduler.add(name, cron_expression, action_list, allow_overlap=allow_overlap)
 
 
 def schedule_remove(name: str) -> dict[str, Any]:
diff --git a/tests/test_scheduler.py b/tests/test_scheduler.py
index 8a26385..cab2b29 100644
--- a/tests/test_scheduler.py
+++ b/tests/test_scheduler.py
@@ -14,6 +14,7 @@
 from automation_file.exceptions import FileAutomationException
 from automation_file.scheduler.cron import CronException, CronExpression
 from automation_file.scheduler.manager import (
+    ScheduledJob,
     Scheduler,
     SchedulerException,
     _safe_execute,
@@ -164,3 +165,41 @@ def test_default_registry_contains_scheduler_ops() -> None:
 
 def test_safe_execute_swallows_exceptions_cleanly() -> None:
     _safe_execute("unit-test", [["FA_does_not_exist"]])
+
+
+def test_scheduler_skips_overlap_by_default() -> None:
+    engine = Scheduler()
+    job = ScheduledJob(
+        name="busy",
+        cron=CronExpression.parse("* * * * *"),
+        action_list=[["FA_schedule_list"]],
+    )
+    job.running = True  # pretend previous run is still in flight
+    engine._dispatch(job, dt.datetime(2026, 4, 21, 12, 0))
+    assert job.skipped == 1
+    assert job.runs == 0
+
+
+def test_scheduler_allows_overlap_when_opted_in() -> None:
+    engine = Scheduler()
+    job = ScheduledJob(
+        name="parallel",
+        cron=CronExpression.parse("* * * * *"),
+        action_list=[["FA_schedule_list"]],
+        allow_overlap=True,
+    )
+    job.running = True
+    engine._dispatch(job, dt.datetime(2026, 4, 21, 12, 0))
+    assert job.runs == 1
+    assert job.skipped == 0
+
+
+def test_scheduled_job_snapshot_includes_overlap_fields() -> None:
+    engine = Scheduler()
+    try:
+        snapshot = engine.add("watch", "* * * * *", [["FA_schedule_list"]])
+        assert snapshot["allow_overlap"] is False
+        assert snapshot["running"] is False
+        assert snapshot["skipped"] == 0
+    finally:
+        engine.shutdown()

From 461579e8098cd1bcd674d14535095b5495b5be3b Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:18:15 +0800
Subject: [PATCH 24/38] Add cross-backend copy via URI scheme routing

---
 automation_file/__init__.py             |   3 +
 automation_file/core/action_registry.py |   2 +
 automation_file/remote/cross_backend.py | 175 ++++++++++++++++++++++++
 tests/test_cross_backend.py             |  87 ++++++++++++
 4 files changed, 267 insertions(+)
 create mode 100644 automation_file/remote/cross_backend.py
 create mode 100644 tests/test_cross_backend.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 5e3b508..07b11d6 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -99,6 +99,7 @@
     azure_blob_instance,
     register_azure_blob_ops,
 )
+from automation_file.remote.cross_backend import CrossBackendException, copy_between
 from automation_file.remote.dropbox_api import (
     DropboxClient,
     dropbox_instance,
@@ -276,6 +277,8 @@ def __getattr__(name: str) -> Any:
     "FTPException",
     "ftp_instance",
     "register_ftp_ops",
+    "CrossBackendException",
+    "copy_between",
     # Server / Project / Utils
     "TCPActionServer",
     "start_autocontrol_socket_server",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index e7fc2a7..8c851f2 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -149,6 +149,7 @@ def _http_commands() -> dict[str, Command]:
 
 def _utils_commands() -> dict[str, Command]:
     from automation_file.core import checksum, manifest
+    from automation_file.remote import cross_backend
     from automation_file.utils import deduplicate, fast_find, grep, rotate
 
     return {
@@ -161,6 +162,7 @@ def _utils_commands() -> dict[str, Command]:
         "FA_verify_manifest": manifest.verify_manifest,
         "FA_grep": grep.grep_files,
         "FA_rotate_backups": rotate.rotate_backups,
+        "FA_copy_between": cross_backend.copy_between,
     }
 
 
diff --git a/automation_file/remote/cross_backend.py b/automation_file/remote/cross_backend.py
new file mode 100644
index 0000000..0f80c1f
--- /dev/null
+++ b/automation_file/remote/cross_backend.py
@@ -0,0 +1,175 @@
+"""Cross-backend copy — stream a file from one storage backend to another.
+
+``copy_between(source, target)`` resolves each URI to (backend, parameters),
+downloads the source to a private temp file, then uploads from that temp
+file to the target. Every backend already exposes ``*_download_file`` /
+``*_upload_file`` primitives — this module just picks the right pair and
+cleans up the intermediate temp file.
+
+Supported URI schemes:
+
+* ``local:/absolute/path`` or a bare filesystem path
+* ``s3://bucket/key``
+* ``azure://container/blob``
+* ``dropbox:/path``
+* ``sftp:/remote/path``
+* ``ftp:/remote/path``
+* ``http://...`` / ``https://...`` (source only)
+
+Callers must have previously initialised every backend they reference
+(``s3_instance.later_init``, etc.) — this helper does not manage sessions.
+"""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+from urllib.parse import urlparse
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+
+class CrossBackendException(FileAutomationException):
+    """Raised when a URI is malformed or refers to an unknown backend."""
+
+
+def copy_between(source: str, target: str) -> bool:
+    """Copy the object at ``source`` to ``target`` via a local temp file.
+
+    Returns True when both the download and the upload reported success.
+    """
+    downloader = _resolve_downloader(source)
+    uploader = _resolve_uploader(target)
+    with tempfile.NamedTemporaryFile(delete=False) as handle:
+        tmp_path = handle.name
+    try:
+        if not downloader(tmp_path):
+            file_automation_logger.error("copy_between: download failed (%s)", source)
+            return False
+        if not uploader(tmp_path):
+            file_automation_logger.error("copy_between: upload failed (%s)", target)
+            return False
+        file_automation_logger.info("copy_between: %s -> %s", source, target)
+        return True
+    finally:
+        Path(tmp_path).unlink(missing_ok=True)
+
+
+def _resolve_downloader(uri: str) -> Callable[[str], bool]:
+    scheme, remainder = _split(uri)
+    if scheme in ("local", ""):
+        return lambda dest: _local_download(remainder, dest)
+    if scheme == "s3":
+        bucket, key = _split_bucket(remainder, "s3")
+        from automation_file.remote.s3.download_ops import s3_download_file
+
+        return lambda dest: bool(s3_download_file(bucket, key, dest))
+    if scheme in ("azure", "az"):
+        container, blob = _split_bucket(remainder, "azure")
+        from automation_file.remote.azure_blob.download_ops import azure_blob_download_file
+
+        return lambda dest: bool(azure_blob_download_file(container, blob, dest))
+    if scheme == "dropbox":
+        from automation_file.remote.dropbox_api.download_ops import dropbox_download_file
+
+        return lambda dest: bool(dropbox_download_file(remainder, dest))
+    if scheme == "sftp":
+        from automation_file.remote.sftp.download_ops import sftp_download_file
+
+        return lambda dest: bool(sftp_download_file(remainder, dest))
+    if scheme == "ftp":
+        from automation_file.remote.ftp.download_ops import ftp_download_file
+
+        return lambda dest: bool(ftp_download_file(remainder, dest))
+    if scheme in ("http", "https"):
+        from automation_file.remote.http_download import download_file
+
+        return lambda dest: bool(download_file(uri, dest))
+    raise CrossBackendException(f"unknown source backend: {scheme!r}")
+
+
+def _resolve_uploader(uri: str) -> Callable[[str], bool]:
+    scheme, remainder = _split(uri)
+    if scheme in ("local", ""):
+        return lambda src: _local_upload(src, remainder)
+    if scheme == "s3":
+        bucket, key = _split_bucket(remainder, "s3")
+        from automation_file.remote.s3.upload_ops import s3_upload_file
+
+        return lambda src: bool(s3_upload_file(src, bucket, key))
+    if scheme in ("azure", "az"):
+        container, blob = _split_bucket(remainder, "azure")
+        from automation_file.remote.azure_blob.upload_ops import azure_blob_upload_file
+
+        return lambda src: bool(azure_blob_upload_file(src, container, blob))
+    if scheme == "dropbox":
+        from automation_file.remote.dropbox_api.upload_ops import dropbox_upload_file
+
+        return lambda src: bool(dropbox_upload_file(src, remainder))
+    if scheme == "sftp":
+        from automation_file.remote.sftp.upload_ops import sftp_upload_file
+
+        return lambda src: bool(sftp_upload_file(src, remainder))
+    if scheme == "ftp":
+        from automation_file.remote.ftp.upload_ops import ftp_upload_file
+
+        return lambda src: bool(ftp_upload_file(src, remainder))
+    raise CrossBackendException(f"unknown target backend: {scheme!r}")
+
+
+_KNOWN_SCHEMES = frozenset(
+    {"local", "s3", "azure", "az", "dropbox", "sftp", "ftp", "http", "https"}
+)
+
+
+def _split(uri: str) -> tuple[str, str]:
+    parsed = urlparse(uri)
+    scheme = parsed.scheme.lower()
+    # Treat single-character "schemes" (Windows drive letters) and URIs with
+    # no scheme at all as local filesystem paths.
+    if len(scheme) <= 1:
+        return "", uri
+    if scheme not in _KNOWN_SCHEMES:
+        raise CrossBackendException(f"unknown backend scheme: {scheme!r}")
+    if scheme in ("http", "https"):
+        return scheme, uri
+    if scheme in ("s3", "azure", "az"):
+        if parsed.netloc:
+            tail = parsed.path.lstrip("/")
+            return scheme, f"{parsed.netloc}/{tail}" if tail else parsed.netloc
+        return scheme, parsed.path.lstrip("/")
+    if scheme == "local":
+        if parsed.netloc:
+            return "local", f"{parsed.netloc}{parsed.path}"
+        return "local", parsed.path
+    # Generic remote path (dropbox, sftp, ftp) — keep the path as given.
+    combined = f"{parsed.netloc}{parsed.path}" if parsed.netloc else parsed.path
+    return scheme, combined.lstrip("/")
+
+
+def _split_bucket(remainder: str, scheme: str) -> tuple[str, str]:
+    if "/" not in remainder:
+        raise CrossBackendException(f"{scheme} URI must be <container>/<key>: {remainder!r}")
+    bucket, key = remainder.split("/", 1)
+    if not bucket or not key:
+        raise CrossBackendException(f"{scheme} URI must be <container>/<key>: {remainder!r}")
+    return bucket, key
+
+
+def _local_download(source_path: str, dest_path: str) -> bool:
+    src = Path(source_path)
+    if not src.is_file():
+        file_automation_logger.error("copy_between: local source missing: %s", src)
+        return False
+    shutil.copyfile(src, dest_path)
+    return True
+
+
+def _local_upload(source_path: str, target_path: str) -> bool:
+    target = Path(target_path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(source_path, target)
+    return True
diff --git a/tests/test_cross_backend.py b/tests/test_cross_backend.py
new file mode 100644
index 0000000..870fcae
--- /dev/null
+++ b/tests/test_cross_backend.py
@@ -0,0 +1,87 @@
+"""Cross-backend copy tests.
+
+Network-backed backends aren't exercised — these tests verify URI parsing,
+local-to-local round trips, and error paths.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from automation_file import (
+    CrossBackendException,
+    build_default_registry,
+    copy_between,
+)
+from automation_file.remote import cross_backend
+
+
+def test_local_to_local_roundtrip(tmp_path: Path) -> None:
+    src = tmp_path / "source.bin"
+    dst = tmp_path / "nested" / "dest.bin"
+    src.write_bytes(b"payload-123")
+    assert copy_between(str(src), str(dst)) is True
+    assert dst.read_bytes() == b"payload-123"
+
+
+def test_local_scheme_prefix(tmp_path: Path) -> None:
+    src = tmp_path / "a.bin"
+    dst = tmp_path / "b.bin"
+    src.write_bytes(b"prefixed")
+    assert copy_between(f"local:{src}", f"local:{dst}") is True
+    assert dst.read_bytes() == b"prefixed"
+
+
+def test_missing_local_source_returns_false(tmp_path: Path) -> None:
+    missing = tmp_path / "nope.bin"
+    dst = tmp_path / "dest.bin"
+    assert copy_between(str(missing), str(dst)) is False
+    assert not dst.exists()
+
+
+def test_unknown_source_scheme_raises() -> None:
+    with pytest.raises(CrossBackendException):
+        copy_between("gopher://a/b", "/tmp/x")
+
+
+def test_unknown_target_scheme_raises(tmp_path: Path) -> None:
+    src = tmp_path / "x"
+    src.write_bytes(b"x")
+    with pytest.raises(CrossBackendException):
+        copy_between(str(src), "gopher://a/b")
+
+
+def test_s3_uri_without_key_raises() -> None:
+    with pytest.raises(CrossBackendException):
+        cross_backend._split_bucket("bucket-only", "s3")
+
+
+def test_default_registry_contains_copy_between() -> None:
+    registry = build_default_registry()
+    assert "FA_copy_between" in registry
+
+
+def test_split_parses_s3_uri() -> None:
+    scheme, remainder = cross_backend._split("s3://my-bucket/path/to/file.txt")
+    assert scheme == "s3"
+    assert remainder == "my-bucket/path/to/file.txt"
+
+
+def test_split_parses_azure_uri() -> None:
+    scheme, remainder = cross_backend._split("azure://container/blob.bin")
+    assert scheme == "azure"
+    assert remainder == "container/blob.bin"
+
+
+def test_split_parses_sftp_uri() -> None:
+    scheme, remainder = cross_backend._split("sftp:/remote/dir/file.bin")
+    assert scheme == "sftp"
+    assert remainder == "remote/dir/file.bin"
+
+
+def test_split_parses_http_uri_preserves_full_url() -> None:
+    scheme, remainder = cross_backend._split("https://example.org/foo")
+    assert scheme == "https"
+    assert remainder.startswith("https://")

From c5843517db7e8151357c53d854ba2034d027a8d9 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:20:38 +0800
Subject: [PATCH 25/38] Add action ACL for TCP + HTTP servers

---
 automation_file/__init__.py           |   3 +
 automation_file/server/action_acl.py  |  64 +++++++++++++++
 automation_file/server/http_server.py |  15 +++-
 automation_file/server/tcp_server.py  |  21 ++++-
 tests/test_action_acl.py              |  43 ++++++++++
 tests/test_server_acl.py              | 109 ++++++++++++++++++++++++++
 6 files changed, 252 insertions(+), 3 deletions(-)
 create mode 100644 automation_file/server/action_acl.py
 create mode 100644 tests/test_action_acl.py
 create mode 100644 tests/test_server_acl.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 07b11d6..c039c16 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -150,6 +150,7 @@
     schedule_remove_all,
     scheduler,
 )
+from automation_file.server.action_acl import ActionACL, ActionNotPermittedException
 from automation_file.server.http_server import HTTPActionServer, start_http_action_server
 from automation_file.server.tcp_server import (
     TCPActionServer,
@@ -284,6 +285,8 @@ def __getattr__(name: str) -> Any:
     "start_autocontrol_socket_server",
     "HTTPActionServer",
     "start_http_action_server",
+    "ActionACL",
+    "ActionNotPermittedException",
     "ProjectBuilder",
     "create_project_dir",
     "get_dir_files_as_list",
diff --git a/automation_file/server/action_acl.py b/automation_file/server/action_acl.py
new file mode 100644
index 0000000..e6f2472
--- /dev/null
+++ b/automation_file/server/action_acl.py
@@ -0,0 +1,64 @@
+"""Action allow/deny list applied by :mod:`tcp_server` / :mod:`http_server`.
+
+Policies are configured at server start; every incoming payload is run through
+:meth:`ActionACL.filter` before dispatch. If any referenced action is denied
+the whole payload is rejected — partial execution would leave the caller in an
+ambiguous state.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from automation_file.exceptions import FileAutomationException
+
+
+class ActionNotPermittedException(FileAutomationException):
+    """Raised when a payload references an action the ACL forbids."""
+
+
+@dataclass(frozen=True)
+class ActionACL:
+    """Allow/deny list for inbound action names.
+
+    * ``allowed`` — when non-empty, only names in this set are accepted.
+      ``None`` (the default) disables the allowlist.
+    * ``denied`` — names in this set are always rejected. Checked after
+      ``allowed`` so an explicit deny overrides an allowlist match.
+    """
+
+    allowed: frozenset[str] | None = None
+    denied: frozenset[str] = field(default_factory=frozenset)
+
+    @classmethod
+    def build(
+        cls,
+        allowed: Iterable[str] | None = None,
+        denied: Iterable[str] | None = None,
+    ) -> ActionACL:
+        return cls(
+            allowed=frozenset(allowed) if allowed is not None else None,
+            denied=frozenset(denied or ()),
+        )
+
+    def is_allowed(self, name: str) -> bool:
+        if name in self.denied:
+            return False
+        return self.allowed is None or name in self.allowed
+
+    def enforce(self, payload: object) -> None:
+        """Raise :class:`ActionNotPermittedException` if any action is denied."""
+        for name in self._iter_names(payload):
+            if not self.is_allowed(name):
+                raise ActionNotPermittedException(f"action not permitted: {name}")
+
+    @staticmethod
+    def _iter_names(payload: object) -> Iterable[str]:
+        if isinstance(payload, dict):
+            payload = payload.get("actions", [])
+        if not isinstance(payload, list):
+            return
+        for entry in payload:
+            if isinstance(entry, list) and entry and isinstance(entry[0], str):
+                yield entry[0]
diff --git a/automation_file/server/http_server.py b/automation_file/server/http_server.py
index 97e1dfc..f7bf960 100644
--- a/automation_file/server/http_server.py
+++ b/automation_file/server/http_server.py
@@ -19,6 +19,7 @@
 from automation_file.core.action_executor import execute_action
 from automation_file.exceptions import TCPAuthException
 from automation_file.logging_config import file_automation_logger
+from automation_file.server.action_acl import ActionACL, ActionNotPermittedException
 from automation_file.server.network_guards import ensure_loopback
 
 _DEFAULT_HOST = "127.0.0.1"
@@ -47,6 +48,15 @@ def do_POST(self) -> None:  # pylint: disable=invalid-name — BaseHTTPRequestHa
             self._send_json(HTTPStatus.BAD_REQUEST, {"error": str(error)})
             return
 
+        acl: ActionACL | None = getattr(self.server, "action_acl", None)
+        if acl is not None:
+            try:
+                acl.enforce(payload)
+            except ActionNotPermittedException as error:
+                file_automation_logger.warning("http_server acl: %r", error)
+                self._send_json(HTTPStatus.FORBIDDEN, {"error": str(error)})
+                return
+
         try:
             results = execute_action(payload)
         except Exception as error:  # pylint: disable=broad-except
@@ -96,9 +106,11 @@ def __init__(
         server_address: tuple[str, int],
         handler_class: type = _HTTPActionHandler,
         shared_secret: str | None = None,
+        action_acl: ActionACL | None = None,
     ) -> None:
         super().__init__(server_address, handler_class)
         self.shared_secret: str | None = shared_secret
+        self.action_acl: ActionACL | None = action_acl
 
 
 def start_http_action_server(
@@ -106,6 +118,7 @@ def start_http_action_server(
     port: int = _DEFAULT_PORT,
     allow_non_loopback: bool = False,
     shared_secret: str | None = None,
+    action_acl: ActionACL | None = None,
 ) -> HTTPActionServer:
     """Start the HTTP action server on a background thread."""
     if not allow_non_loopback:
@@ -114,7 +127,7 @@ def start_http_action_server(
         file_automation_logger.warning(
             "http_server: non-loopback bind without shared_secret is insecure",
         )
-    server = HTTPActionServer((host, port), shared_secret=shared_secret)
+    server = HTTPActionServer((host, port), shared_secret=shared_secret, action_acl=action_acl)
     thread = threading.Thread(target=server.serve_forever, daemon=True)
     thread.start()
     file_automation_logger.info(
diff --git a/automation_file/server/tcp_server.py b/automation_file/server/tcp_server.py
index 625d8f5..e46420b 100644
--- a/automation_file/server/tcp_server.py
+++ b/automation_file/server/tcp_server.py
@@ -22,6 +22,7 @@
 from automation_file.core.action_executor import execute_action
 from automation_file.exceptions import TCPAuthException
 from automation_file.logging_config import file_automation_logger
+from automation_file.server.action_acl import ActionACL, ActionNotPermittedException
 from automation_file.server.network_guards import ensure_loopback
 
 _DEFAULT_HOST = "localhost"
@@ -63,11 +64,17 @@ def handle(self) -> None:
 
         try:
             payload = json.loads(command_string)
+            acl: ActionACL | None = getattr(self.server, "action_acl", None)
+            if acl is not None:
+                acl.enforce(payload)
             results = execute_action(payload)
             for key, value in results.items():
                 self._send_line(f"{key} -> {value}")
         except json.JSONDecodeError as error:
             self._send_line(f"json error: {error!r}")
+        except ActionNotPermittedException as error:
+            file_automation_logger.warning("tcp_server acl: %r", error)
+            self._send_line(f"forbidden: {error}")
         except Exception as error:  # pylint: disable=broad-except
             file_automation_logger.error("tcp_server handler: %r", error)
             self._send_line(f"execution error: {error!r}")
@@ -109,10 +116,12 @@ def __init__(
         server_address: tuple[str, int],
         request_handler_class: type,
         shared_secret: str | None = None,
+        action_acl: ActionACL | None = None,
     ) -> None:
         super().__init__(server_address, request_handler_class)
         self.close_flag: bool = False
         self.shared_secret: str | None = shared_secret
+        self.action_acl: ActionACL | None = action_acl
 
 
 def start_autocontrol_socket_server(
@@ -120,12 +129,15 @@ def start_autocontrol_socket_server(
     port: int = _DEFAULT_PORT,
     allow_non_loopback: bool = False,
     shared_secret: str | None = None,
+    action_acl: ActionACL | None = None,
 ) -> TCPActionServer:
     """Start the action-dispatching TCP server on a background thread.
 
     ``shared_secret`` turns on per-connection authentication: clients must send
     ``AUTH <secret>\\n`` followed by the JSON payload. Binding to a non-loopback
-    address without a shared secret is strongly discouraged.
+    address without a shared secret is strongly discouraged. ``action_acl``
+    filters each incoming payload; any referenced action the ACL denies causes
+    the whole request to be rejected.
     """
     if not allow_non_loopback:
         ensure_loopback(host)
@@ -133,7 +145,12 @@ def start_autocontrol_socket_server(
         file_automation_logger.warning(
             "tcp_server: non-loopback bind without shared_secret is insecure",
         )
-    server = TCPActionServer((host, port), _TCPServerHandler, shared_secret=shared_secret)
+    server = TCPActionServer(
+        (host, port),
+        _TCPServerHandler,
+        shared_secret=shared_secret,
+        action_acl=action_acl,
+    )
     thread = threading.Thread(target=server.serve_forever, daemon=True)
     thread.start()
     file_automation_logger.info(
diff --git a/tests/test_action_acl.py b/tests/test_action_acl.py
new file mode 100644
index 0000000..2aa407e
--- /dev/null
+++ b/tests/test_action_acl.py
@@ -0,0 +1,43 @@
+"""Unit tests for the shared action ACL."""
+
+from __future__ import annotations
+
+import pytest
+
+from automation_file import ActionACL, ActionNotPermittedException
+
+
+def test_default_acl_permits_all() -> None:
+    acl = ActionACL()
+    acl.enforce([["FA_anything"], ["FA_other", {}]])
+    assert acl.is_allowed("anything") is True
+
+
+def test_allowlist_rejects_outside_names() -> None:
+    acl = ActionACL.build(allowed=["FA_list"])
+    with pytest.raises(ActionNotPermittedException):
+        acl.enforce([["FA_run_shell", {"argv": ["echo"]}]])
+
+
+def test_allowlist_permits_listed_names() -> None:
+    acl = ActionACL.build(allowed=["FA_list", "FA_create_file"])
+    acl.enforce([["FA_list"], ["FA_create_file", {"file_path": "x"}]])
+
+
+def test_denylist_wins_over_allowlist() -> None:
+    acl = ActionACL.build(allowed=["FA_foo"], denied=["FA_foo"])
+    with pytest.raises(ActionNotPermittedException):
+        acl.enforce([["FA_foo"]])
+
+
+def test_enforce_accepts_dict_payload_shape() -> None:
+    acl = ActionACL.build(allowed=["FA_foo"])
+    acl.enforce({"actions": [["FA_foo"]]})
+    with pytest.raises(ActionNotPermittedException):
+        acl.enforce({"actions": [["FA_bar"]]})
+
+
+def test_enforce_ignores_malformed_entries() -> None:
+    acl = ActionACL.build(allowed=["FA_foo"])
+    # Non-list / empty / non-string-first entries are skipped silently.
+    acl.enforce([[], [1, 2], "garbage"])  # type: ignore[list-item]
diff --git a/tests/test_server_acl.py b/tests/test_server_acl.py
new file mode 100644
index 0000000..89aadf3
--- /dev/null
+++ b/tests/test_server_acl.py
@@ -0,0 +1,109 @@
+"""TCP + HTTP server ACL integration tests."""
+
+from __future__ import annotations
+
+import json
+import socket
+from http.client import HTTPConnection
+
+from automation_file import (
+    ActionACL,
+    start_autocontrol_socket_server,
+    start_http_action_server,
+)
+from automation_file.core.action_executor import executor
+
+_END_MARKER = b"Return_Data_Over_JE\n"
+
+
+def _ensure_echo() -> None:
+    if "test_acl_echo" not in executor.registry:
+        executor.registry.register("test_acl_echo", lambda value=0: value)
+    if "test_acl_forbidden" not in executor.registry:
+        executor.registry.register("test_acl_forbidden", lambda: "nope")
+
+
+def _tcp_send(host: str, port: int, payload: bytes) -> bytes:
+    with socket.create_connection((host, port), timeout=3) as sock:
+        sock.sendall(payload)
+        chunks: list[bytes] = []
+        while True:
+            chunk = sock.recv(4096)
+            if not chunk:
+                break
+            chunks.append(chunk)
+            if _END_MARKER in b"".join(chunks):
+                break
+        return b"".join(chunks)
+
+
+def test_tcp_server_rejects_denied_action() -> None:
+    _ensure_echo()
+    acl = ActionACL.build(denied=["test_acl_forbidden"])
+    server = start_autocontrol_socket_server(host="127.0.0.1", port=0, action_acl=acl)
+    host, port = server.server_address
+    try:
+        response = _tcp_send(host, port, b'[["test_acl_forbidden"]]')
+        assert b"forbidden" in response
+        response_ok = _tcp_send(host, port, b'[["test_acl_echo", {"value": 7}]]')
+        assert b"7" in response_ok
+    finally:
+        server.shutdown()
+
+
+def test_tcp_server_allowlist_rejects_outside_actions() -> None:
+    _ensure_echo()
+    acl = ActionACL.build(allowed=["test_acl_echo"])
+    server = start_autocontrol_socket_server(host="127.0.0.1", port=0, action_acl=acl)
+    host, port = server.server_address
+    try:
+        response = _tcp_send(host, port, b'[["test_acl_forbidden"]]')
+        assert b"forbidden" in response
+    finally:
+        server.shutdown()
+
+
+def test_http_server_rejects_denied_action_with_403() -> None:
+    _ensure_echo()
+    acl = ActionACL.build(denied=["test_acl_forbidden"])
+    server = start_http_action_server(host="127.0.0.1", port=0, action_acl=acl)
+    host, port = server.server_address
+    try:
+        body = json.dumps([["test_acl_forbidden"]]).encode("utf-8")
+        conn = HTTPConnection(host, port, timeout=3)
+        conn.request(
+            "POST",
+            "/actions",
+            body=body,
+            headers={"Content-Type": "application/json", "Content-Length": str(len(body))},
+        )
+        response = conn.getresponse()
+        assert response.status == 403
+        payload = json.loads(response.read().decode("utf-8"))
+        assert "not permitted" in payload["error"]
+        conn.close()
+    finally:
+        server.shutdown()
+
+
+def test_http_server_allows_permitted_action() -> None:
+    _ensure_echo()
+    acl = ActionACL.build(allowed=["test_acl_echo"])
+    server = start_http_action_server(host="127.0.0.1", port=0, action_acl=acl)
+    host, port = server.server_address
+    try:
+        body = json.dumps([["test_acl_echo", {"value": 42}]]).encode("utf-8")
+        conn = HTTPConnection(host, port, timeout=3)
+        conn.request(
+            "POST",
+            "/actions",
+            body=body,
+            headers={"Content-Type": "application/json", "Content-Length": str(len(body))},
+        )
+        response = conn.getresponse()
+        assert response.status == 200
+        payload = json.loads(response.read().decode("utf-8"))
+        assert 42 in payload.values()
+        conn.close()
+    finally:
+        server.shutdown()

From fc7da7aa202ab4072e744e7a21944a39a1b8e68b Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:21:42 +0800
Subject: [PATCH 26/38] Add config hot reload via ConfigWatcher

---
 automation_file/__init__.py            |  2 +
 automation_file/core/config_watcher.py | 96 ++++++++++++++++++++++++++
 tests/test_config_watcher.py           | 83 ++++++++++++++++++++++
 3 files changed, 181 insertions(+)
 create mode 100644 automation_file/core/config_watcher.py
 create mode 100644 tests/test_config_watcher.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index c039c16..6bbc9f2 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -26,6 +26,7 @@
     verify_checksum,
 )
 from automation_file.core.config import AutomationConfig, ConfigException
+from automation_file.core.config_watcher import ConfigWatcher
 from automation_file.core.dag_executor import execute_action_dag
 from automation_file.core.json_store import read_action_json, write_action_json
 from automation_file.core.manifest import ManifestException, verify_manifest, write_manifest
@@ -347,6 +348,7 @@ def __getattr__(name: str) -> Any:
     # Config / secrets
     "AutomationConfig",
     "ConfigException",
+    "ConfigWatcher",
     "ChainedSecretProvider",
     "EnvSecretProvider",
     "FileSecretProvider",
diff --git a/automation_file/core/config_watcher.py b/automation_file/core/config_watcher.py
new file mode 100644
index 0000000..80c7679
--- /dev/null
+++ b/automation_file/core/config_watcher.py
@@ -0,0 +1,96 @@
+"""Polling hot-reload for ``automation_file.toml``.
+
+``ConfigWatcher`` runs a small background thread that checks the config file's
+mtime + size every ``interval`` seconds. When either changes it reloads via
+:meth:`AutomationConfig.load` and fires the user-supplied ``on_change``
+callback with the fresh config. Errors during reload are logged but do not
+terminate the watcher — the next successful reload picks up where we left
+off.
+
+We use polling rather than watchdog here: it's one file, cross-platform, and
+the reload cadence is inherently human-scale (seconds, not milliseconds).
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from pathlib import Path
+
+from automation_file.core.config import AutomationConfig, ConfigException
+from automation_file.core.secrets import ChainedSecretProvider
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+OnChange = Callable[[AutomationConfig], None]
+
+
+class ConfigWatcher:
+    """Polls ``path`` and invokes ``on_change`` whenever the file changes."""
+
+    def __init__(
+        self,
+        path: str | Path,
+        on_change: OnChange,
+        *,
+        interval: float = 2.0,
+        provider: ChainedSecretProvider | None = None,
+    ) -> None:
+        if interval <= 0:
+            raise ConfigException("interval must be positive")
+        self._path = Path(path)
+        self._on_change = on_change
+        self._interval = interval
+        self._provider = provider
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._last_fingerprint: tuple[float, int] | None = None
+
+    def start(self) -> AutomationConfig:
+        """Load the config once, arm the watcher, and return the initial load."""
+        config = AutomationConfig.load(self._path, provider=self._provider)
+        self._last_fingerprint = self._fingerprint()
+        self._stop.clear()
+        thread = threading.Thread(target=self._run, name="fa-config-watcher", daemon=True)
+        thread.start()
+        self._thread = thread
+        file_automation_logger.info(
+            "config_watcher: watching %s (interval=%.2fs)", self._path, self._interval
+        )
+        return config
+
+    def stop(self, timeout: float = 5.0) -> None:
+        self._stop.set()
+        thread = self._thread
+        self._thread = None
+        if thread is not None and thread.is_alive():
+            thread.join(timeout=timeout)
+
+    def check_once(self) -> bool:
+        """Reload if the file changed since the last call. Returns True on reload."""
+        fingerprint = self._fingerprint()
+        if fingerprint == self._last_fingerprint:
+            return False
+        self._last_fingerprint = fingerprint
+        try:
+            config = AutomationConfig.load(self._path, provider=self._provider)
+        except FileAutomationException as err:
+            file_automation_logger.error("config_watcher: reload failed: %r", err)
+            return False
+        try:
+            self._on_change(config)
+        except FileAutomationException as err:
+            file_automation_logger.error("config_watcher: on_change raised: %r", err)
+        return True
+
+    def _fingerprint(self) -> tuple[float, int]:
+        try:
+            stat = self._path.stat()
+        except OSError:
+            return (0.0, 0)
+        return (stat.st_mtime, stat.st_size)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            self.check_once()
+            self._stop.wait(self._interval)
diff --git a/tests/test_config_watcher.py b/tests/test_config_watcher.py
new file mode 100644
index 0000000..7394102
--- /dev/null
+++ b/tests/test_config_watcher.py
@@ -0,0 +1,83 @@
+"""Tests for the config hot-reload watcher."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import pytest
+
+from automation_file import AutomationConfig, ConfigException, ConfigWatcher
+
+_INITIAL = """
+[defaults]
+dedup_seconds = 30
+"""
+
+_UPDATED = """
+[defaults]
+dedup_seconds = 99
+"""
+
+
+def test_start_returns_initial_config(tmp_path: Path) -> None:
+    config_path = tmp_path / "automation_file.toml"
+    config_path.write_text(_INITIAL, encoding="utf-8")
+    seen: list[AutomationConfig] = []
+    watcher = ConfigWatcher(config_path, seen.append, interval=1.0)
+    try:
+        initial = watcher.start()
+        assert initial.section("defaults")["dedup_seconds"] == 30
+    finally:
+        watcher.stop()
+
+
+def test_check_once_detects_mtime_change(tmp_path: Path) -> None:
+    config_path = tmp_path / "automation_file.toml"
+    config_path.write_text(_INITIAL, encoding="utf-8")
+    seen: list[AutomationConfig] = []
+    watcher = ConfigWatcher(config_path, seen.append, interval=60.0)
+    try:
+        watcher.start()
+        # Force a fingerprint delta: rewrite with different content + push mtime forward
+        time.sleep(0.01)
+        config_path.write_text(_UPDATED, encoding="utf-8")
+        assert watcher.check_once() is True
+        assert seen and seen[-1].section("defaults")["dedup_seconds"] == 99
+    finally:
+        watcher.stop()
+
+
+def test_check_once_returns_false_when_unchanged(tmp_path: Path) -> None:
+    config_path = tmp_path / "automation_file.toml"
+    config_path.write_text(_INITIAL, encoding="utf-8")
+    watcher = ConfigWatcher(config_path, lambda _cfg: None, interval=60.0)
+    try:
+        watcher.start()
+        assert watcher.check_once() is False
+    finally:
+        watcher.stop()
+
+
+def test_zero_interval_rejected(tmp_path: Path) -> None:
+    with pytest.raises(ConfigException):
+        ConfigWatcher(tmp_path / "x.toml", lambda _cfg: None, interval=0)
+
+
+def test_reload_failure_logged_but_not_fatal(tmp_path: Path) -> None:
+    config_path = tmp_path / "automation_file.toml"
+    config_path.write_text(_INITIAL, encoding="utf-8")
+    seen: list[AutomationConfig] = []
+    watcher = ConfigWatcher(config_path, seen.append, interval=60.0)
+    try:
+        watcher.start()
+        time.sleep(0.01)
+        config_path.write_text("not = [valid", encoding="utf-8")
+        # Reload raises ConfigException internally; watcher just logs and returns False.
+        assert watcher.check_once() is False
+        # Fix the file and verify we pick back up.
+        time.sleep(0.01)
+        config_path.write_text(_UPDATED, encoding="utf-8")
+        assert watcher.check_once() is True
+    finally:
+        watcher.stop()

From 000f19bb6112f1c3822cd0fa065ac3be1042adb7 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:23:22 +0800
Subject: [PATCH 27/38] Add opt-in variable substitution for action lists

---
 automation_file/__init__.py             |  3 +
 automation_file/core/action_executor.py | 10 ++-
 automation_file/core/substitution.py    | 82 +++++++++++++++++++++++++
 tests/test_substitution.py              | 79 ++++++++++++++++++++++++
 4 files changed, 173 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/core/substitution.py
 create mode 100644 tests/test_substitution.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 6bbc9f2..8ed9ea6 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -54,6 +54,7 @@
     default_provider,
     resolve_secret_refs,
 )
+from automation_file.core.substitution import SubstitutionException, substitute
 from automation_file.local.dir_ops import copy_dir, create_dir, remove_dir_tree, rename_dir
 from automation_file.local.file_ops import (
     copy_all_file_to_dir,
@@ -205,6 +206,8 @@ def __getattr__(name: str) -> Any:
     "execute_files",
     "validate_action",
     "retry_on_transient",
+    "substitute",
+    "SubstitutionException",
     "add_command_to_executor",
     "read_action_json",
     "write_action_json",
diff --git a/automation_file/core/action_executor.py b/automation_file/core/action_executor.py
index b7c7972..e50abd5 100644
--- a/automation_file/core/action_executor.py
+++ b/automation_file/core/action_executor.py
@@ -21,6 +21,7 @@
 
 from automation_file.core.action_registry import ActionRegistry, build_default_registry
 from automation_file.core.json_store import read_action_json
+from automation_file.core.substitution import substitute as substitute_payload
 from automation_file.exceptions import ExecuteActionException, ValidationException
 from automation_file.logging_config import file_automation_logger
 
@@ -95,14 +96,19 @@ def execute_action(
         action_list: list | Mapping[str, Any],
         dry_run: bool = False,
         validate_first: bool = False,
+        substitute: bool = False,
     ) -> dict[str, Any]:
         """Execute every action; return ``{"execute: <action>": result|repr(error)}``.
 
         ``dry_run=True`` logs and records the resolved name without invoking the
         command. ``validate_first=True`` runs :meth:`validate` before touching
-        any action so a typo aborts the whole batch up-front.
+        any action so a typo aborts the whole batch up-front. ``substitute=True``
+        expands ``${env:...}`` / ``${date:...}`` / ``${uuid}`` / ``${cwd}``
+        placeholders inside every string in the payload.
         """
         actions = self._coerce(action_list)
+        if substitute:
+            actions = substitute_payload(actions)  # type: ignore[assignment]
         if validate_first:
             self.validate(actions)
         results: dict[str, Any] = {}
@@ -190,12 +196,14 @@ def execute_action(
     action_list: list | Mapping[str, Any],
     dry_run: bool = False,
     validate_first: bool = False,
+    substitute: bool = False,
 ) -> dict[str, Any]:
     """Module-level shim that delegates to the shared executor."""
     return executor.execute_action(
         action_list,
         dry_run=dry_run,
         validate_first=validate_first,
+        substitute=substitute,
     )
 
 
diff --git a/automation_file/core/substitution.py b/automation_file/core/substitution.py
new file mode 100644
index 0000000..67578c3
--- /dev/null
+++ b/automation_file/core/substitution.py
@@ -0,0 +1,82 @@
+"""Opt-in variable substitution for action list payloads.
+
+When ``execute_action(..., substitute=True)`` is used, every string inside
+the action list is scanned for ``${kind}`` / ``${kind:arg}`` placeholders
+before dispatch. The following kinds are supported:
+
+* ``${env:NAME}`` — value of the ``NAME`` environment variable (empty when unset)
+* ``${date:FMT}`` — ``datetime.now().strftime(FMT)``; bare ``${date}`` yields ISO
+* ``${uuid}`` — a fresh ``uuid.uuid4().hex``
+* ``${cwd}`` — ``os.getcwd()``
+
+Unknown kinds raise :class:`SubstitutionException` so typos surface loudly
+rather than leaking literal ``${...}`` into paths.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import uuid
+from collections.abc import Callable
+from datetime import datetime
+
+from automation_file.exceptions import FileAutomationException
+
+_PATTERN = re.compile(r"\$\{([a-zA-Z_][a-zA-Z0-9_]*)(?::([^}]*))?\}")
+
+
+class SubstitutionException(FileAutomationException):
+    """Raised when a ``${...}`` reference names an unknown kind."""
+
+
+def substitute(payload: object) -> object:
+    """Return a deep copy of ``payload`` with every ``${...}`` expanded."""
+    if isinstance(payload, str):
+        return _expand(payload)
+    if isinstance(payload, list):
+        return [substitute(item) for item in payload]
+    if isinstance(payload, dict):
+        return {key: substitute(value) for key, value in payload.items()}
+    if isinstance(payload, tuple):
+        return tuple(substitute(item) for item in payload)
+    return payload
+
+
+def _expand(text: str) -> str:
+    def replace(match: re.Match[str]) -> str:
+        kind = match.group(1).lower()
+        arg = match.group(2)
+        handler = _HANDLERS.get(kind)
+        if handler is None:
+            raise SubstitutionException(f"unknown substitution kind: {match.group(0)}")
+        return handler(arg)
+
+    return _PATTERN.sub(replace, text)
+
+
+def _env(arg: str | None) -> str:
+    if not arg:
+        raise SubstitutionException("${env:NAME} requires a variable name")
+    return os.environ.get(arg, "")
+
+
+def _date(arg: str | None) -> str:
+    fmt = arg or "%Y-%m-%dT%H:%M:%S"
+    return datetime.now().strftime(fmt)
+
+
+def _uuid(_arg: str | None) -> str:
+    return uuid.uuid4().hex
+
+
+def _cwd(_arg: str | None) -> str:
+    return os.getcwd()
+
+
+_HANDLERS: dict[str, Callable[[str | None], str]] = {
+    "env": _env,
+    "date": _date,
+    "uuid": _uuid,
+    "cwd": _cwd,
+}
diff --git a/tests/test_substitution.py b/tests/test_substitution.py
new file mode 100644
index 0000000..d145f8d
--- /dev/null
+++ b/tests/test_substitution.py
@@ -0,0 +1,79 @@
+"""Tests for opt-in variable substitution."""
+
+from __future__ import annotations
+
+import os
+import re
+import uuid
+from pathlib import Path
+
+import pytest
+
+from automation_file import SubstitutionException, execute_action, substitute
+from automation_file.core.action_executor import executor
+
+
+def test_substitute_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("FA_SUB_TEST", "hello")
+    assert substitute("${env:FA_SUB_TEST}/suffix") == "hello/suffix"
+
+
+def test_substitute_env_missing_returns_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("FA_SUB_ABSENT", raising=False)
+    assert substitute("X${env:FA_SUB_ABSENT}Y") == "XY"
+
+
+def test_substitute_date_with_format() -> None:
+    result = substitute("${date:%Y}")
+    assert isinstance(result, str)
+    assert re.fullmatch(r"\d{4}", result)
+
+
+def test_substitute_uuid_is_hex32() -> None:
+    result = substitute("${uuid}")
+    assert isinstance(result, str)
+    uuid.UUID(hex=result)
+
+
+def test_substitute_cwd() -> None:
+    assert substitute("${cwd}") == os.getcwd()
+
+
+def test_substitute_nested_structures(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("FA_NESTED", "nested-value")
+    payload = [
+        ["FA_create_file", {"file_path": "${env:FA_NESTED}"}],
+        ["other", ["${cwd}", "static"]],
+    ]
+    result = substitute(payload)
+    assert result[0][1]["file_path"] == "nested-value"
+    assert result[1][1][0] == os.getcwd()
+    assert result[1][1][1] == "static"
+
+
+def test_unknown_substitution_raises() -> None:
+    with pytest.raises(SubstitutionException):
+        substitute("${unknown:foo}")
+
+
+def test_env_without_arg_raises() -> None:
+    with pytest.raises(SubstitutionException):
+        substitute("${env:}")
+
+
+def test_execute_action_substitutes_when_opted_in(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("FA_EXEC_SUB", "echoed")
+    if "test_sub_echo" not in executor.registry:
+        executor.registry.register("test_sub_echo", lambda value: value)
+    results = execute_action([["test_sub_echo", {"value": "${env:FA_EXEC_SUB}"}]], substitute=True)
+    assert "echoed" in next(iter(results.values()))
+
+
+def test_execute_action_leaves_strings_untouched_by_default(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("FA_EXEC_SUB", "echoed")
+    if "test_sub_echo" not in executor.registry:
+        executor.registry.register("test_sub_echo", lambda value: value)
+    results = execute_action([["test_sub_echo", {"value": "${env:FA_EXEC_SUB}"}]])
+    assert "${env:FA_EXEC_SUB}" in next(iter(results.values()))

From bd1c7204658439fcd288b0062d3f0e2fb8f1fef5 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:24:31 +0800
Subject: [PATCH 28/38] Add conditional execution primitives (if_exists /
 if_newer / if_size_gt)

---
 automation_file/__init__.py             |   4 +
 automation_file/core/action_registry.py |   5 ++
 automation_file/local/conditional.py    |  87 ++++++++++++++++++++
 tests/test_conditional.py               | 103 ++++++++++++++++++++++++
 4 files changed, 199 insertions(+)
 create mode 100644 automation_file/local/conditional.py
 create mode 100644 tests/test_conditional.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 8ed9ea6..a926c65 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -55,6 +55,7 @@
     resolve_secret_refs,
 )
 from automation_file.core.substitution import SubstitutionException, substitute
+from automation_file.local.conditional import if_exists, if_newer, if_size_gt
 from automation_file.local.dir_ops import copy_dir, create_dir, remove_dir_tree, rename_dir
 from automation_file.local.file_ops import (
     copy_all_file_to_dir,
@@ -246,6 +247,9 @@ def __getattr__(name: str) -> Any:
     "unzip_all",
     "safe_join",
     "is_within",
+    "if_exists",
+    "if_newer",
+    "if_size_gt",
     # Remote
     "download_file",
     "validate_http_url",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index 8c851f2..f2ebcc9 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -67,6 +67,7 @@ def event_dict(self) -> dict[str, Command]:
 
 def _local_commands() -> dict[str, Command]:
     from automation_file.local import (
+        conditional,
         dir_ops,
         file_ops,
         json_edit,
@@ -108,6 +109,10 @@ def _local_commands() -> dict[str, Command]:
         "FA_unzip_file": zip_ops.unzip_file,
         "FA_read_zip_file": zip_ops.read_zip_file,
         "FA_unzip_all": zip_ops.unzip_all,
+        # Conditional dispatch
+        "FA_if_exists": conditional.if_exists,
+        "FA_if_newer": conditional.if_newer,
+        "FA_if_size_gt": conditional.if_size_gt,
     }
 
 
diff --git a/automation_file/local/conditional.py b/automation_file/local/conditional.py
new file mode 100644
index 0000000..21bf15e
--- /dev/null
+++ b/automation_file/local/conditional.py
@@ -0,0 +1,87 @@
+"""Conditional execution primitives for action lists.
+
+``FA_if_exists`` / ``FA_if_newer`` / ``FA_if_size_gt`` dispatch one of two
+inline action lists based on a filesystem predicate. Each branch is itself
+an action list and is executed through the shared
+:class:`~automation_file.core.action_executor.ActionExecutor`, so results /
+errors are captured exactly the way a top-level invocation would be.
+
+A branch may be ``None`` (or omitted) to mean "do nothing". The function
+returns::
+
+    {"matched": bool, "results": {...}}
+
+where ``results`` is the return value of ``execute_action`` for the branch
+that actually ran, or ``{}`` when the matching branch was empty.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+
+def if_exists(
+    path: str,
+    then: list | None = None,
+    else_: list | None = None,
+) -> dict[str, Any]:
+    """Run ``then`` when ``path`` exists, otherwise run ``else_``."""
+    return _dispatch(Path(path).exists(), then, else_, reason=f"exists({path})")
+
+
+def if_newer(
+    path: str,
+    reference: str,
+    then: list | None = None,
+    else_: list | None = None,
+) -> dict[str, Any]:
+    """Run ``then`` when ``path`` is newer than ``reference``.
+
+    Missing ``path`` is treated as "not newer". Missing ``reference`` is
+    treated as "anything else wins" — ``then`` runs.
+    """
+    source = Path(path)
+    ref = Path(reference)
+    if not source.exists():
+        matched = False
+    elif not ref.exists():
+        matched = True
+    else:
+        matched = source.stat().st_mtime > ref.stat().st_mtime
+    return _dispatch(matched, then, else_, reason=f"newer({path},{reference})")
+
+
+def if_size_gt(
+    path: str,
+    bytes_threshold: int,
+    then: list | None = None,
+    else_: list | None = None,
+) -> dict[str, Any]:
+    """Run ``then`` when ``path`` exists and is strictly larger than ``bytes_threshold``."""
+    if bytes_threshold < 0:
+        raise FileAutomationException("bytes_threshold must be >= 0")
+    source = Path(path)
+    matched = source.is_file() and source.stat().st_size > bytes_threshold
+    return _dispatch(matched, then, else_, reason=f"size_gt({path},{bytes_threshold})")
+
+
+def _dispatch(
+    matched: bool,
+    then: list | None,
+    else_: list | None,
+    *,
+    reason: str,
+) -> dict[str, Any]:
+    branch = then if matched else else_
+    file_automation_logger.info("conditional %s -> matched=%s", reason, matched)
+    if not branch:
+        return {"matched": matched, "results": {}}
+    # Deferred import keeps this module cheap to load and avoids an import cycle
+    # with ActionExecutor at module-initialisation time.
+    from automation_file.core.action_executor import executor
+
+    return {"matched": matched, "results": executor.execute_action(branch)}
diff --git a/tests/test_conditional.py b/tests/test_conditional.py
new file mode 100644
index 0000000..02b7f6a
--- /dev/null
+++ b/tests/test_conditional.py
@@ -0,0 +1,103 @@
+"""Tests for FA_if_exists / FA_if_newer / FA_if_size_gt conditional primitives."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from automation_file import (
+    build_default_registry,
+    if_exists,
+    if_newer,
+    if_size_gt,
+)
+from automation_file.core.action_executor import executor
+from automation_file.exceptions import FileAutomationException
+
+
+def _register_probes() -> None:
+    if "test_cond_then" not in executor.registry:
+        executor.registry.register("test_cond_then", lambda: "then-ran")
+    if "test_cond_else" not in executor.registry:
+        executor.registry.register("test_cond_else", lambda: "else-ran")
+
+
+def test_if_exists_runs_then_when_path_present(tmp_path: Path) -> None:
+    _register_probes()
+    target = tmp_path / "here.txt"
+    target.write_text("x", encoding="utf-8")
+    outcome = if_exists(str(target), then=[["test_cond_then"]], else_=[["test_cond_else"]])
+    assert outcome["matched"] is True
+    assert any("then-ran" in str(v) for v in outcome["results"].values())
+
+
+def test_if_exists_runs_else_when_path_missing(tmp_path: Path) -> None:
+    _register_probes()
+    outcome = if_exists(
+        str(tmp_path / "absent"), then=[["test_cond_then"]], else_=[["test_cond_else"]]
+    )
+    assert outcome["matched"] is False
+    assert any("else-ran" in str(v) for v in outcome["results"].values())
+
+
+def test_if_exists_empty_branch_returns_no_results(tmp_path: Path) -> None:
+    outcome = if_exists(str(tmp_path / "absent"))
+    assert outcome == {"matched": False, "results": {}}
+
+
+def test_if_newer_true_when_source_newer(tmp_path: Path) -> None:
+    _register_probes()
+    older = tmp_path / "old.txt"
+    newer = tmp_path / "new.txt"
+    older.write_text("o", encoding="utf-8")
+    newer.write_text("n", encoding="utf-8")
+    os.utime(older, (1_700_000_000, 1_700_000_000))
+    os.utime(newer, (1_700_001_000, 1_700_001_000))
+    outcome = if_newer(str(newer), str(older), then=[["test_cond_then"]])
+    assert outcome["matched"] is True
+
+
+def test_if_newer_false_when_source_older(tmp_path: Path) -> None:
+    _register_probes()
+    older = tmp_path / "old.txt"
+    newer = tmp_path / "new.txt"
+    older.write_text("o", encoding="utf-8")
+    newer.write_text("n", encoding="utf-8")
+    os.utime(older, (1_700_000_000, 1_700_000_000))
+    os.utime(newer, (1_700_001_000, 1_700_001_000))
+    outcome = if_newer(str(older), str(newer), then=[["test_cond_then"]])
+    assert outcome["matched"] is False
+
+
+def test_if_newer_missing_reference_treats_source_as_newer(tmp_path: Path) -> None:
+    source = tmp_path / "src.txt"
+    source.write_text("x", encoding="utf-8")
+    outcome = if_newer(str(source), str(tmp_path / "absent"))
+    assert outcome["matched"] is True
+
+
+def test_if_size_gt_true(tmp_path: Path) -> None:
+    path = tmp_path / "big.bin"
+    path.write_bytes(b"x" * 100)
+    outcome = if_size_gt(str(path), 50)
+    assert outcome["matched"] is True
+
+
+def test_if_size_gt_false(tmp_path: Path) -> None:
+    path = tmp_path / "small.bin"
+    path.write_bytes(b"x" * 10)
+    outcome = if_size_gt(str(path), 50)
+    assert outcome["matched"] is False
+
+
+def test_if_size_gt_rejects_negative_threshold(tmp_path: Path) -> None:
+    with pytest.raises(FileAutomationException):
+        if_size_gt(str(tmp_path / "x"), -1)
+
+
+def test_default_registry_wires_conditionals() -> None:
+    registry = build_default_registry()
+    for name in ("FA_if_exists", "FA_if_newer", "FA_if_size_gt"):
+        assert name in registry

From a340aed585501f66ca0813e77cedbc5401252d5a Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:27:53 +0800
Subject: [PATCH 29/38] Add SQLite audit log for action execution

---
 automation_file/__init__.py   |   3 +
 automation_file/core/audit.py | 140 ++++++++++++++++++++++++++++++++++
 tests/test_audit.py           | 118 ++++++++++++++++++++++++++++
 3 files changed, 261 insertions(+)
 create mode 100644 automation_file/core/audit.py
 create mode 100644 tests/test_audit.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index a926c65..000603f 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -19,6 +19,7 @@
     validate_action,
 )
 from automation_file.core.action_registry import ActionRegistry, build_default_registry
+from automation_file.core.audit import AuditException, AuditLog
 from automation_file.core.callback_executor import CallbackExecutor
 from automation_file.core.checksum import (
     ChecksumMismatchException,
@@ -313,6 +314,8 @@ def __getattr__(name: str) -> Any:
     "ManifestException",
     "write_manifest",
     "verify_manifest",
+    "AuditException",
+    "AuditLog",
     # Triggers
     "FileWatcher",
     "TriggerManager",
diff --git a/automation_file/core/audit.py b/automation_file/core/audit.py
new file mode 100644
index 0000000..ce573e1
--- /dev/null
+++ b/automation_file/core/audit.py
@@ -0,0 +1,140 @@
+"""SQLite-backed audit log for executed actions.
+
+``AuditLog(db_path)`` opens (or creates) a single-table SQLite database and
+appends one row per action execution. Rows carry the timestamp, action name,
+a JSON-encoded snapshot of the payload, the result / error repr, and the
+duration in milliseconds.
+
+Writes use a short-lived connection per call (``check_same_thread=False``
+semantics) so the log is safe to share between background worker threads
+and the scheduler. Readers call :meth:`AuditLog.recent` to pull the most
+recent N rows.
+
+The module deliberately avoids buffering / background queues: every row is
+persisted synchronously with an ``INSERT`` inside a ``with connect(..)`` so
+a crash at most loses the currently-executing action.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+import time
+from contextlib import closing
+from pathlib import Path
+from typing import Any
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS audit (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts REAL NOT NULL,
+    action TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    result TEXT,
+    error TEXT,
+    duration_ms REAL NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_audit_ts ON audit (ts DESC);
+"""
+
+
+class AuditException(FileAutomationException):
+    """Raised when the audit log cannot be opened or written."""
+
+
+class AuditLog:
+    """Synchronous SQLite audit log."""
+
+    def __init__(self, db_path: str | Path) -> None:
+        self._db_path = Path(db_path)
+        self._lock = threading.Lock()
+        try:
+            self._db_path.parent.mkdir(parents=True, exist_ok=True)
+            with closing(self._connect()) as conn:
+                conn.executescript(_SCHEMA)
+                conn.commit()
+        except (OSError, sqlite3.DatabaseError) as err:
+            raise AuditException(f"cannot open audit log {self._db_path}: {err}") from err
+
+    def record(
+        self,
+        action: str,
+        payload: Any,
+        *,
+        result: Any = None,
+        error: BaseException | None = None,
+        duration_ms: float = 0.0,
+    ) -> None:
+        """Append a single audit row. Never raises — failures are logged only."""
+        row = (
+            time.time(),
+            action,
+            _safe_json(payload),
+            _safe_json(result) if result is not None else None,
+            repr(error) if error is not None else None,
+            float(duration_ms),
+        )
+        try:
+            with self._lock, closing(self._connect()) as conn:
+                conn.execute(
+                    "INSERT INTO audit (ts, action, payload, result, error, duration_ms)"
+                    " VALUES (?, ?, ?, ?, ?, ?)",
+                    row,
+                )
+                conn.commit()
+        except sqlite3.DatabaseError as err:
+            file_automation_logger.error("audit.record failed: %r", err)
+
+    def recent(self, limit: int = 100) -> list[dict[str, Any]]:
+        """Return the newest ``limit`` rows, newest first."""
+        if limit <= 0:
+            return []
+        with closing(self._connect()) as conn:
+            cursor = conn.execute(
+                "SELECT id, ts, action, payload, result, error, duration_ms"
+                " FROM audit ORDER BY ts DESC LIMIT ?",
+                (limit,),
+            )
+            rows = cursor.fetchall()
+        return [
+            {
+                "id": row[0],
+                "ts": row[1],
+                "action": row[2],
+                "payload": json.loads(row[3]) if row[3] else None,
+                "result": json.loads(row[4]) if row[4] else None,
+                "error": row[5],
+                "duration_ms": row[6],
+            }
+            for row in rows
+        ]
+
+    def count(self) -> int:
+        with closing(self._connect()) as conn:
+            cursor = conn.execute("SELECT COUNT(*) FROM audit")
+            (total,) = cursor.fetchone()
+        return int(total)
+
+    def purge(self, older_than_seconds: float) -> int:
+        """Delete rows older than ``older_than_seconds`` and return the row count."""
+        if older_than_seconds <= 0:
+            raise AuditException("older_than_seconds must be positive")
+        cutoff = time.time() - older_than_seconds
+        with self._lock, closing(self._connect()) as conn:
+            cursor = conn.execute("DELETE FROM audit WHERE ts < ?", (cutoff,))
+            conn.commit()
+            return int(cursor.rowcount)
+
+    def _connect(self) -> sqlite3.Connection:
+        return sqlite3.connect(self._db_path, timeout=5.0)
+
+
+def _safe_json(value: Any) -> str:
+    try:
+        return json.dumps(value, default=repr, ensure_ascii=False)
+    except (TypeError, ValueError):
+        return json.dumps(repr(value), ensure_ascii=False)
diff --git a/tests/test_audit.py b/tests/test_audit.py
new file mode 100644
index 0000000..756c372
--- /dev/null
+++ b/tests/test_audit.py
@@ -0,0 +1,118 @@
+"""Tests for the SQLite-backed action audit log."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import pytest
+
+from automation_file import AuditException, AuditLog
+
+
+def test_audit_log_creates_parent_directory(tmp_path: Path) -> None:
+    db_path = tmp_path / "nested" / "audit.sqlite"
+    log = AuditLog(db_path)
+    assert db_path.exists()
+    assert log.count() == 0
+
+
+def test_record_and_recent_roundtrip(tmp_path: Path) -> None:
+    log = AuditLog(tmp_path / "audit.sqlite")
+    log.record("FA_copy_file", {"src": "a", "dst": "b"}, result={"ok": True}, duration_ms=12.5)
+    rows = log.recent()
+    assert len(rows) == 1
+    row = rows[0]
+    assert row["action"] == "FA_copy_file"
+    assert row["payload"] == {"src": "a", "dst": "b"}
+    assert row["result"] == {"ok": True}
+    assert row["error"] is None
+    assert row["duration_ms"] == 12.5
+
+
+def test_record_error_stores_repr(tmp_path: Path) -> None:
+    log = AuditLog(tmp_path / "audit.sqlite")
+    err = ValueError("boom")
+    log.record("FA_test", {"x": 1}, error=err, duration_ms=0.0)
+    row = log.recent()[0]
+    assert row["error"] is not None
+    assert "ValueError" in row["error"]
+    assert "boom" in row["error"]
+    assert row["result"] is None
+
+
+def test_recent_returns_newest_first(tmp_path: Path) -> None:
+    log = AuditLog(tmp_path / "audit.sqlite")
+    log.record("first", {"i": 1})
+    time.sleep(0.01)
+    log.record("second", {"i": 2})
+    time.sleep(0.01)
+    log.record("third", {"i": 3})
+    rows = log.recent()
+    assert [r["action"] for r in rows] == ["third", "second", "first"]
+
+
+def test_recent_respects_limit(tmp_path: Path) -> None:
+    log = AuditLog(tmp_path / "audit.sqlite")
+    for index in range(5):
+        log.record(f"action-{index}", {"i": index})
+    rows = log.recent(limit=2)
+    assert len(rows) == 2
+
+
+def test_recent_zero_limit_returns_empty(tmp_path: Path) -> None:
+    log = AuditLog(tmp_path / "audit.sqlite")
+    log.record("x", {})
+    assert log.recent(limit=0) == []
+
+
+def test_count_reflects_inserts(tmp_path: Path) -> None:
+    log = AuditLog(tmp_path / "audit.sqlite")
+    assert log.count() == 0
+    log.record("a", {})
+    log.record("b", {})
+    assert log.count() == 2
+
+
+def test_purge_removes_old_rows(tmp_path: Path) -> None:
+    log = AuditLog(tmp_path / "audit.sqlite")
+    log.record("old", {})
+    # Backdate the row so it's older than the cutoff.
+    import sqlite3
+
+    with sqlite3.connect(log._db_path) as conn:
+        conn.execute("UPDATE audit SET ts = ? WHERE action = 'old'", (time.time() - 3600,))
+        conn.commit()
+    log.record("fresh", {})
+    removed = log.purge(older_than_seconds=60)
+    assert removed == 1
+    remaining = [row["action"] for row in log.recent()]
+    assert remaining == ["fresh"]
+
+
+def test_purge_rejects_non_positive(tmp_path: Path) -> None:
+    log = AuditLog(tmp_path / "audit.sqlite")
+    with pytest.raises(AuditException):
+        log.purge(0)
+
+
+def test_record_non_serialisable_payload_falls_back_to_repr(tmp_path: Path) -> None:
+    log = AuditLog(tmp_path / "audit.sqlite")
+
+    class Custom:
+        def __repr__(self) -> str:
+            return "<custom>"
+
+    log.record("weird", {"obj": Custom()}, result={"marker": object()})
+    row = log.recent()[0]
+    assert row["action"] == "weird"
+    assert "<custom>" in str(row["payload"])
+    assert row["result"] is not None
+
+
+def test_cannot_open_audit_log_in_missing_root(tmp_path: Path) -> None:
+    # Point at a path whose parent cannot be created (a file, not a dir).
+    blocker = tmp_path / "blocker"
+    blocker.write_text("x", encoding="utf-8")
+    with pytest.raises(AuditException):
+        AuditLog(blocker / "child" / "audit.sqlite")

From f50317380d776e21008ad2d6a1c4d4c1476bd59c Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:30:16 +0800
Subject: [PATCH 30/38] Add file integrity monitor for periodic manifest
 verification

---
 automation_file/__init__.py |   2 +
 automation_file/core/fim.py | 151 ++++++++++++++++++++++++++++++++++++
 tests/test_fim.py           | 140 +++++++++++++++++++++++++++++++++
 3 files changed, 293 insertions(+)
 create mode 100644 automation_file/core/fim.py
 create mode 100644 tests/test_fim.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 000603f..26d3030 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -29,6 +29,7 @@
 from automation_file.core.config import AutomationConfig, ConfigException
 from automation_file.core.config_watcher import ConfigWatcher
 from automation_file.core.dag_executor import execute_action_dag
+from automation_file.core.fim import IntegrityMonitor
 from automation_file.core.json_store import read_action_json, write_action_json
 from automation_file.core.manifest import ManifestException, verify_manifest, write_manifest
 from automation_file.core.package_loader import PackageLoader
@@ -316,6 +317,7 @@ def __getattr__(name: str) -> Any:
     "verify_manifest",
     "AuditException",
     "AuditLog",
+    "IntegrityMonitor",
     # Triggers
     "FileWatcher",
     "TriggerManager",
diff --git a/automation_file/core/fim.py b/automation_file/core/fim.py
new file mode 100644
index 0000000..12051ef
--- /dev/null
+++ b/automation_file/core/fim.py
@@ -0,0 +1,151 @@
+"""File integrity monitoring (FIM) — periodic manifest verification.
+
+``IntegrityMonitor(root, manifest_path)`` runs a background thread that
+re-verifies the tree against a previously-written manifest at a fixed
+interval. When drift is detected (missing or modified files) the monitor
+
+1. invokes the optional ``on_drift`` callback with the verification summary,
+2. emits an ``error``-level notification through the supplied
+   :class:`~automation_file.notify.NotificationManager` (defaults to the
+   process-wide singleton), and
+3. logs a single warning describing the counts.
+
+This is the "watchdog" side of manifests: once a baseline has been written
+with :func:`write_manifest`, a monitor keeps checking that the tree still
+matches and alerts when it does not. Extras (new files not in the manifest)
+do not count as drift by default — mirrors the posture of ``verify_manifest``.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from automation_file.core.manifest import ManifestException, verify_manifest
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+from automation_file.notify import NotificationManager, notification_manager
+
+OnDrift = Callable[[dict[str, Any]], None]
+
+
+class IntegrityMonitor:
+    """Periodically verify a manifest and fire alerts on drift."""
+
+    def __init__(
+        self,
+        root: str | Path,
+        manifest_path: str | Path,
+        *,
+        interval: float = 60.0,
+        on_drift: OnDrift | None = None,
+        manager: NotificationManager | None = None,
+        alert_on_extra: bool = False,
+    ) -> None:
+        if interval <= 0:
+            raise FileAutomationException("interval must be positive")
+        self._root = Path(root)
+        self._manifest_path = Path(manifest_path)
+        self._interval = float(interval)
+        self._on_drift = on_drift
+        self._manager = manager or notification_manager
+        self._alert_on_extra = bool(alert_on_extra)
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._last_summary: dict[str, Any] | None = None
+
+    @property
+    def last_summary(self) -> dict[str, Any] | None:
+        return self._last_summary
+
+    def start(self) -> None:
+        """Arm the monitor. The first verification runs on the next tick."""
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._stop.clear()
+        thread = threading.Thread(target=self._run, name="fa-integrity-monitor", daemon=True)
+        thread.start()
+        self._thread = thread
+        file_automation_logger.info(
+            "integrity_monitor: watching %s against %s (interval=%.1fs)",
+            self._root,
+            self._manifest_path,
+            self._interval,
+        )
+
+    def stop(self, timeout: float = 5.0) -> None:
+        self._stop.set()
+        thread = self._thread
+        self._thread = None
+        if thread is not None and thread.is_alive():
+            thread.join(timeout=timeout)
+
+    def check_once(self) -> dict[str, Any]:
+        """Run one verification pass and return the summary."""
+        try:
+            summary = verify_manifest(self._root, self._manifest_path)
+        except (ManifestException, FileAutomationException) as err:
+            file_automation_logger.error("integrity_monitor: verify failed: %r", err)
+            summary = {
+                "matched": [],
+                "missing": [],
+                "modified": [],
+                "extra": [],
+                "ok": False,
+                "error": repr(err),
+            }
+        self._last_summary = summary
+        if self._is_drift(summary):
+            self._handle_drift(summary)
+        return summary
+
+    def _is_drift(self, summary: dict[str, Any]) -> bool:
+        if summary.get("error"):
+            return True
+        if summary.get("missing") or summary.get("modified"):
+            return True
+        return bool(self._alert_on_extra and summary.get("extra"))
+
+    def _handle_drift(self, summary: dict[str, Any]) -> None:
+        file_automation_logger.warning(
+            "integrity_monitor: drift detected missing=%d modified=%d extra=%d",
+            len(summary.get("missing") or []),
+            len(summary.get("modified") or []),
+            len(summary.get("extra") or []),
+        )
+        if self._on_drift is not None:
+            try:
+                self._on_drift(summary)
+            except FileAutomationException as err:
+                file_automation_logger.error("integrity_monitor: on_drift raised: %r", err)
+        body = _format_body(summary)
+        try:
+            self._manager.notify(
+                subject=f"integrity drift: {self._root}",
+                body=body,
+                level="error",
+            )
+        except FileAutomationException as err:
+            file_automation_logger.error("integrity_monitor: notify failed: %r", err)
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            self._stop.wait(self._interval)
+            if self._stop.is_set():
+                break
+            self.check_once()
+
+
+def _format_body(summary: dict[str, Any]) -> str:
+    parts: list[str] = []
+    if summary.get("error"):
+        parts.append(f"error: {summary['error']}")
+    for key in ("missing", "modified", "extra"):
+        items = summary.get(key) or []
+        if items:
+            preview = ", ".join(items[:5])
+            suffix = f" (+{len(items) - 5} more)" if len(items) > 5 else ""
+            parts.append(f"{key}: {preview}{suffix}")
+    return "\n".join(parts) if parts else "no drift detected"
diff --git a/tests/test_fim.py b/tests/test_fim.py
new file mode 100644
index 0000000..87ffd18
--- /dev/null
+++ b/tests/test_fim.py
@@ -0,0 +1,140 @@
+"""Tests for the file integrity monitor."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from automation_file import IntegrityMonitor, write_manifest
+from automation_file.exceptions import FileAutomationException
+from automation_file.notify import NotificationManager
+from automation_file.notify.sinks import NotificationSink
+
+
+class _Recorder(NotificationSink):
+    name = "recorder"
+
+    def __init__(self) -> None:
+        self.messages: list[tuple[str, str, str]] = []
+
+    def send(self, subject: str, body: str, level: str = "info") -> None:
+        self.messages.append((subject, body, level))
+
+
+def _build_tree(tmp_path: Path) -> tuple[Path, Path]:
+    root = tmp_path / "tree"
+    root.mkdir()
+    (root / "a.txt").write_text("alpha", encoding="utf-8")
+    (root / "b.txt").write_text("bravo", encoding="utf-8")
+    manifest_path = tmp_path / "manifest.json"
+    write_manifest(root, manifest_path)
+    return root, manifest_path
+
+
+def test_check_once_clean_tree(tmp_path: Path) -> None:
+    root, manifest_path = _build_tree(tmp_path)
+    monitor = IntegrityMonitor(root, manifest_path)
+    summary = monitor.check_once()
+    assert summary["ok"] is True
+    assert monitor.last_summary is summary
+
+
+def test_check_once_detects_modified_file_and_notifies(tmp_path: Path) -> None:
+    root, manifest_path = _build_tree(tmp_path)
+    (root / "a.txt").write_text("tampered", encoding="utf-8")
+    manager = NotificationManager(dedup_seconds=0.0)
+    recorder = _Recorder()
+    manager.register(recorder)
+    monitor = IntegrityMonitor(root, manifest_path, manager=manager)
+    summary = monitor.check_once()
+    assert summary["ok"] is False
+    assert "a.txt" in summary["modified"]
+    assert recorder.messages, "expected a drift notification"
+    subject, body, level = recorder.messages[0]
+    assert level == "error"
+    assert "integrity drift" in subject
+    assert "a.txt" in body
+
+
+def test_check_once_detects_missing_file(tmp_path: Path) -> None:
+    root, manifest_path = _build_tree(tmp_path)
+    (root / "b.txt").unlink()
+    manager = NotificationManager(dedup_seconds=0.0)
+    recorder = _Recorder()
+    manager.register(recorder)
+    monitor = IntegrityMonitor(root, manifest_path, manager=manager)
+    summary = monitor.check_once()
+    assert "b.txt" in summary["missing"]
+    assert recorder.messages
+
+
+def test_extras_ignored_by_default(tmp_path: Path) -> None:
+    root, manifest_path = _build_tree(tmp_path)
+    (root / "new.txt").write_text("novel", encoding="utf-8")
+    manager = NotificationManager(dedup_seconds=0.0)
+    recorder = _Recorder()
+    manager.register(recorder)
+    monitor = IntegrityMonitor(root, manifest_path, manager=manager)
+    summary = monitor.check_once()
+    assert "new.txt" in summary["extra"]
+    assert summary["ok"] is True
+    assert recorder.messages == []
+
+
+def test_alert_on_extra_flag(tmp_path: Path) -> None:
+    root, manifest_path = _build_tree(tmp_path)
+    (root / "new.txt").write_text("novel", encoding="utf-8")
+    manager = NotificationManager(dedup_seconds=0.0)
+    recorder = _Recorder()
+    manager.register(recorder)
+    monitor = IntegrityMonitor(root, manifest_path, manager=manager, alert_on_extra=True)
+    monitor.check_once()
+    assert recorder.messages
+
+
+def test_on_drift_callback_invoked(tmp_path: Path) -> None:
+    root, manifest_path = _build_tree(tmp_path)
+    (root / "a.txt").write_text("tampered", encoding="utf-8")
+    seen: list[dict[str, Any]] = []
+    monitor = IntegrityMonitor(
+        root,
+        manifest_path,
+        manager=NotificationManager(dedup_seconds=0.0),
+        on_drift=seen.append,
+    )
+    monitor.check_once()
+    assert len(seen) == 1
+    assert "a.txt" in seen[0]["modified"]
+
+
+def test_missing_manifest_treated_as_drift(tmp_path: Path) -> None:
+    root = tmp_path / "tree"
+    root.mkdir()
+    (root / "a.txt").write_text("alpha", encoding="utf-8")
+    manager = NotificationManager(dedup_seconds=0.0)
+    recorder = _Recorder()
+    manager.register(recorder)
+    monitor = IntegrityMonitor(root, tmp_path / "missing.json", manager=manager)
+    summary = monitor.check_once()
+    assert summary["ok"] is False
+    assert "error" in summary
+    assert recorder.messages
+
+
+def test_positive_interval_required(tmp_path: Path) -> None:
+    root, manifest_path = _build_tree(tmp_path)
+    with pytest.raises(FileAutomationException):
+        IntegrityMonitor(root, manifest_path, interval=0)
+
+
+def test_start_and_stop_thread(tmp_path: Path) -> None:
+    root, manifest_path = _build_tree(tmp_path)
+    monitor = IntegrityMonitor(root, manifest_path, interval=0.05)
+    monitor.start()
+    try:
+        # Second start is a no-op.
+        monitor.start()
+    finally:
+        monitor.stop(timeout=1.0)

From 1907f60f363cd77a48eb9cef023f8a88565d486a Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:32:32 +0800
Subject: [PATCH 31/38] Add Telegram / Discord / Teams / PagerDuty notification
 sinks

---
 automation_file/__init__.py        |   8 ++
 automation_file/notify/__init__.py |   8 ++
 automation_file/notify/sinks.py    | 216 +++++++++++++++++++++++++++++
 tests/test_notify_sinks_extra.py   | 134 ++++++++++++++++++
 4 files changed, 366 insertions(+)
 create mode 100644 tests/test_notify_sinks_extra.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 26d3030..039985c 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -88,11 +88,15 @@
     zip_info,
 )
 from automation_file.notify import (
+    DiscordSink,
     EmailSink,
     NotificationException,
     NotificationManager,
     NotificationSink,
+    PagerDutySink,
     SlackSink,
+    TeamsSink,
+    TelegramSink,
     WebhookSink,
     notification_manager,
     notify_send,
@@ -348,11 +352,15 @@ def __getattr__(name: str) -> Any:
     "progress_registry",
     "register_progress_ops",
     # Notifications
+    "DiscordSink",
     "EmailSink",
     "NotificationException",
     "NotificationManager",
     "NotificationSink",
+    "PagerDutySink",
     "SlackSink",
+    "TeamsSink",
+    "TelegramSink",
     "WebhookSink",
     "notification_manager",
     "notify_send",
diff --git a/automation_file/notify/__init__.py b/automation_file/notify/__init__.py
index 1191a04..a5600b7 100644
--- a/automation_file/notify/__init__.py
+++ b/automation_file/notify/__init__.py
@@ -17,18 +17,26 @@
     register_notify_ops,
 )
 from automation_file.notify.sinks import (
+    DiscordSink,
     EmailSink,
     NotificationSink,
+    PagerDutySink,
     SlackSink,
+    TeamsSink,
+    TelegramSink,
     WebhookSink,
 )
 
 __all__ = [
+    "DiscordSink",
     "EmailSink",
     "NotificationException",
     "NotificationManager",
     "NotificationSink",
+    "PagerDutySink",
     "SlackSink",
+    "TeamsSink",
+    "TelegramSink",
     "WebhookSink",
     "notification_manager",
     "notify_send",
diff --git a/automation_file/notify/sinks.py b/automation_file/notify/sinks.py
index bae65d7..3576e47 100644
--- a/automation_file/notify/sinks.py
+++ b/automation_file/notify/sinks.py
@@ -194,6 +194,218 @@ def __repr__(self) -> str:
         )
 
 
+class TelegramSink(NotificationSink):
+    """Telegram Bot API sink.
+
+    ``bot_token`` is a secret — it's combined into the request URL and never
+    logged. ``chat_id`` identifies the target channel or user.
+    """
+
+    _LEVEL_PREFIX: ClassVar[dict[str, str]] = {
+        "info": "",
+        "warning": "⚠️ ",
+        "error": "🚨 ",
+    }
+    _API_HOST: ClassVar[str] = "https://api.telegram.org"
+
+    def __init__(
+        self,
+        bot_token: str,
+        chat_id: str | int,
+        *,
+        name: str = "telegram",
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        if not bot_token:
+            raise NotificationException("telegram sink requires a bot_token")
+        if chat_id in (None, ""):
+            raise NotificationException("telegram sink requires a chat_id")
+        self._bot_token = bot_token
+        self.chat_id = chat_id
+        self.name = name
+        self.timeout = timeout
+        self._url = f"{self._API_HOST}/bot{bot_token}/sendMessage"
+        validate_http_url(self._url)
+
+    def send(self, subject: str, body: str, level: str = "info") -> None:
+        self._check_level(level)
+        prefix = self._LEVEL_PREFIX[level]
+        text = f"{prefix}{subject}\n{self._truncate(body)}"
+        payload = {"chat_id": self.chat_id, "text": text, "disable_web_page_preview": True}
+        try:
+            response = requests.post(
+                self._url,
+                data=json.dumps(payload).encode("utf-8"),
+                headers={"Content-Type": "application/json"},
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException as err:
+            raise NotificationException(f"telegram sink {self.name!r} post failed: {err}") from err
+        if response.status_code >= 400:
+            raise NotificationException(
+                f"telegram sink {self.name!r} returned HTTP {response.status_code}"
+            )
+
+    def __repr__(self) -> str:
+        return f"TelegramSink(name={self.name!r}, chat_id={self.chat_id!r})"
+
+
+class DiscordSink(NotificationSink):
+    """Discord incoming-webhook sink — POSTs ``{content}`` to the webhook URL."""
+
+    _LEVEL_PREFIX: ClassVar[dict[str, str]] = {
+        "info": "",
+        "warning": ":warning: ",
+        "error": ":rotating_light: ",
+    }
+    # Discord caps message content at 2000 characters.
+    _MAX_CONTENT: ClassVar[int] = 1900
+
+    def __init__(
+        self,
+        webhook_url: str,
+        *,
+        name: str = "discord",
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        validate_http_url(webhook_url)
+        self._url = webhook_url
+        self.name = name
+        self.timeout = timeout
+
+    def send(self, subject: str, body: str, level: str = "info") -> None:
+        self._check_level(level)
+        prefix = self._LEVEL_PREFIX[level]
+        content = f"{prefix}**{subject}**\n{self._truncate(body)}"
+        if len(content) > self._MAX_CONTENT:
+            content = content[: self._MAX_CONTENT] + "…"
+        try:
+            response = requests.post(
+                self._url,
+                data=json.dumps({"content": content}).encode("utf-8"),
+                headers={"Content-Type": "application/json"},
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException as err:
+            raise NotificationException(f"discord sink {self.name!r} post failed: {err}") from err
+        if response.status_code >= 400:
+            raise NotificationException(
+                f"discord sink {self.name!r} returned HTTP {response.status_code}"
+            )
+
+
+class TeamsSink(NotificationSink):
+    """Microsoft Teams incoming-webhook sink using the legacy MessageCard schema."""
+
+    _LEVEL_COLOR: ClassVar[dict[str, str]] = {
+        "info": "2E86DE",
+        "warning": "E67E22",
+        "error": "C0392B",
+    }
+
+    def __init__(
+        self,
+        webhook_url: str,
+        *,
+        name: str = "teams",
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        validate_http_url(webhook_url)
+        self._url = webhook_url
+        self.name = name
+        self.timeout = timeout
+
+    def send(self, subject: str, body: str, level: str = "info") -> None:
+        self._check_level(level)
+        payload = {
+            "@type": "MessageCard",
+            "@context": "https://schema.org/extensions",
+            "summary": subject,
+            "themeColor": self._LEVEL_COLOR[level],
+            "title": subject,
+            "text": self._truncate(body),
+        }
+        try:
+            response = requests.post(
+                self._url,
+                data=json.dumps(payload).encode("utf-8"),
+                headers={"Content-Type": "application/json"},
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException as err:
+            raise NotificationException(f"teams sink {self.name!r} post failed: {err}") from err
+        if response.status_code >= 400:
+            raise NotificationException(
+                f"teams sink {self.name!r} returned HTTP {response.status_code}"
+            )
+
+
+class PagerDutySink(NotificationSink):
+    """PagerDuty Events API v2 sink.
+
+    ``routing_key`` is the integration key for a PagerDuty service and is
+    treated as a secret. Each ``send`` enqueues a ``trigger`` event unless
+    the level is explicitly ``info``, in which case it sends ``acknowledge``
+    semantics via ``event_action='trigger'`` + ``severity='info'``.
+    """
+
+    _ENQUEUE_URL: ClassVar[str] = "https://events.pagerduty.com/v2/enqueue"
+    _LEVEL_SEVERITY: ClassVar[dict[str, str]] = {
+        "info": "info",
+        "warning": "warning",
+        "error": "error",
+    }
+
+    def __init__(
+        self,
+        routing_key: str,
+        *,
+        source: str = "automation_file",
+        name: str = "pagerduty",
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        if not routing_key:
+            raise NotificationException("pagerduty sink requires a routing_key")
+        self._routing_key = routing_key
+        self.source = source
+        self.name = name
+        self.timeout = timeout
+        validate_http_url(self._ENQUEUE_URL)
+
+    def send(self, subject: str, body: str, level: str = "info") -> None:
+        self._check_level(level)
+        payload = {
+            "routing_key": self._routing_key,
+            "event_action": "trigger",
+            "payload": {
+                "summary": subject,
+                "source": self.source,
+                "severity": self._LEVEL_SEVERITY[level],
+                "custom_details": {"body": self._truncate(body)},
+            },
+        }
+        try:
+            response = requests.post(
+                self._ENQUEUE_URL,
+                data=json.dumps(payload).encode("utf-8"),
+                headers={"Content-Type": "application/json"},
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException as err:
+            raise NotificationException(f"pagerduty sink {self.name!r} post failed: {err}") from err
+        if response.status_code >= 400:
+            raise NotificationException(
+                f"pagerduty sink {self.name!r} returned HTTP {response.status_code}"
+            )
+
+    def __repr__(self) -> str:
+        return f"PagerDutySink(name={self.name!r}, source={self.source!r})"
+
+
 def _describe(sink: NotificationSink) -> dict[str, Any]:
     info: dict[str, Any] = {"name": sink.name, "type": type(sink).__name__}
     if isinstance(sink, WebhookSink):
@@ -202,6 +414,10 @@ def _describe(sink: NotificationSink) -> dict[str, Any]:
         info["host"] = sink.host
         info["port"] = sink.port
         info["recipients"] = sink.recipients
+    elif isinstance(sink, TelegramSink):
+        info["chat_id"] = sink.chat_id
+    elif isinstance(sink, PagerDutySink):
+        info["source"] = sink.source
     return info
 
 
diff --git a/tests/test_notify_sinks_extra.py b/tests/test_notify_sinks_extra.py
new file mode 100644
index 0000000..b43b373
--- /dev/null
+++ b/tests/test_notify_sinks_extra.py
@@ -0,0 +1,134 @@
+"""Tests for TelegramSink / DiscordSink / TeamsSink / PagerDutySink."""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import patch
+
+import pytest
+
+from automation_file.notify import (
+    DiscordSink,
+    NotificationException,
+    PagerDutySink,
+    TeamsSink,
+    TelegramSink,
+)
+
+
+class _FakeResp:
+    def __init__(self, status_code: int = 200) -> None:
+        self.status_code = status_code
+
+
+def _loaded(post_call) -> dict:
+    return json.loads(post_call.kwargs["data"].decode("utf-8"))
+
+
+def test_telegram_requires_bot_token() -> None:
+    with pytest.raises(NotificationException):
+        TelegramSink("", chat_id="1")
+
+
+def test_telegram_requires_chat_id() -> None:
+    with pytest.raises(NotificationException):
+        TelegramSink("token", chat_id="")
+
+
+def test_telegram_posts_to_bot_endpoint() -> None:
+    sink = TelegramSink("secret-token", chat_id="@channel")
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(200)
+        sink.send("subj", "body", "error")
+    post.assert_called_once()
+    args = post.call_args.args
+    assert args[0] == "https://api.telegram.org/botsecret-token/sendMessage"
+    payload = _loaded(post.call_args)
+    assert payload["chat_id"] == "@channel"
+    assert payload["text"].startswith("🚨 ")
+
+
+def test_telegram_repr_hides_token() -> None:
+    sink = TelegramSink("secret-token", chat_id="42")
+    assert "secret-token" not in repr(sink)
+
+
+def test_telegram_http_error_raises() -> None:
+    sink = TelegramSink("t", chat_id="1")
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(500)
+        with pytest.raises(NotificationException, match="HTTP 500"):
+            sink.send("x", "y")
+
+
+def test_discord_sends_content_field() -> None:
+    sink = DiscordSink("https://discord.com/api/webhooks/1/token")
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(204)
+        sink.send("alert", "details", "warning")
+    payload = _loaded(post.call_args)
+    assert "content" in payload
+    assert payload["content"].startswith(":warning: **alert**")
+
+
+def test_discord_trims_oversized_content() -> None:
+    sink = DiscordSink("https://discord.com/api/webhooks/1/token")
+    big = "x" * 3000
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(204)
+        sink.send("subj", big, "info")
+    payload = _loaded(post.call_args)
+    assert len(payload["content"]) <= 1901
+
+
+def test_teams_sends_message_card() -> None:
+    sink = TeamsSink("https://outlook.office.com/webhook/abc")
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(200)
+        sink.send("subj", "body", "warning")
+    payload = _loaded(post.call_args)
+    assert payload["@type"] == "MessageCard"
+    assert payload["title"] == "subj"
+    assert payload["themeColor"] == "E67E22"
+
+
+def test_pagerduty_requires_routing_key() -> None:
+    with pytest.raises(NotificationException):
+        PagerDutySink("")
+
+
+def test_pagerduty_posts_event_payload() -> None:
+    sink = PagerDutySink("rk-secret")
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(202)
+        sink.send("disk full", "/var is at 99%", "error")
+    args = post.call_args.args
+    assert args[0] == "https://events.pagerduty.com/v2/enqueue"
+    payload = _loaded(post.call_args)
+    assert payload["routing_key"] == "rk-secret"
+    assert payload["event_action"] == "trigger"
+    assert payload["payload"]["severity"] == "error"
+    assert payload["payload"]["summary"] == "disk full"
+    assert payload["payload"]["custom_details"]["body"] == "/var is at 99%"
+
+
+def test_pagerduty_http_error_raises() -> None:
+    sink = PagerDutySink("rk")
+    with patch("automation_file.notify.sinks.requests.post") as post:
+        post.return_value = _FakeResp(400)
+        with pytest.raises(NotificationException, match="HTTP 400"):
+            sink.send("x", "y")
+
+
+def test_pagerduty_repr_hides_routing_key() -> None:
+    sink = PagerDutySink("super-secret-routing-key")
+    assert "super-secret-routing-key" not in repr(sink)
+
+
+def test_new_sinks_surface_via_facade() -> None:
+    import automation_file
+
+    assert automation_file.DiscordSink is DiscordSink
+    assert automation_file.TeamsSink is TeamsSink
+    assert automation_file.TelegramSink is TelegramSink
+    assert automation_file.PagerDutySink is PagerDutySink

From 28720f14b3d8d36f2052fc6d4f8684edec2916d0 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:34:26 +0800
Subject: [PATCH 32/38] Add HTTPActionClient Python SDK for the HTTP action
 server

---
 automation_file/__init__.py           |   3 +
 automation_file/client/__init__.py    |   7 ++
 automation_file/client/http_client.py | 132 ++++++++++++++++++++++++++
 tests/test_http_client.py             | 120 +++++++++++++++++++++++
 4 files changed, 262 insertions(+)
 create mode 100644 automation_file/client/__init__.py
 create mode 100644 automation_file/client/http_client.py
 create mode 100644 tests/test_http_client.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 039985c..2e7e523 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -9,6 +9,7 @@
 
 from typing import TYPE_CHECKING, Any
 
+from automation_file.client import HTTPActionClient, HTTPActionClientException
 from automation_file.core.action_executor import (
     ActionExecutor,
     add_command_to_executor,
@@ -299,6 +300,8 @@ def __getattr__(name: str) -> Any:
     "start_autocontrol_socket_server",
     "HTTPActionServer",
     "start_http_action_server",
+    "HTTPActionClient",
+    "HTTPActionClientException",
     "ActionACL",
     "ActionNotPermittedException",
     "ProjectBuilder",
diff --git a/automation_file/client/__init__.py b/automation_file/client/__init__.py
new file mode 100644
index 0000000..3678359
--- /dev/null
+++ b/automation_file/client/__init__.py
@@ -0,0 +1,7 @@
+"""Client SDK for talking to a running ``HTTPActionServer``."""
+
+from __future__ import annotations
+
+from automation_file.client.http_client import HTTPActionClient, HTTPActionClientException
+
+__all__ = ["HTTPActionClient", "HTTPActionClientException"]
diff --git a/automation_file/client/http_client.py b/automation_file/client/http_client.py
new file mode 100644
index 0000000..d5a56b2
--- /dev/null
+++ b/automation_file/client/http_client.py
@@ -0,0 +1,132 @@
+"""Python SDK for :class:`~automation_file.server.http_server.HTTPActionServer`.
+
+``HTTPActionClient(base_url, *, shared_secret=None)`` wraps a single
+``requests.Session`` and exposes ``execute(actions)`` which POSTs the JSON
+action list to ``<base_url>/actions``. The client is intentionally thin:
+it handles auth header assembly, response-code checking, and error
+translation, but makes no attempt to mirror ``ActionExecutor``'s API
+surface — callers pass the same action-list shape they would pass to
+``execute_action``.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+
+import requests
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+from automation_file.remote.url_validator import validate_http_url
+
+_DEFAULT_TIMEOUT = 30.0
+_ACTIONS_PATH = "/actions"
+
+
+class HTTPActionClientException(FileAutomationException):
+    """Raised when the server rejects a request or the response is malformed."""
+
+
+class HTTPActionClient:
+    """Synchronous SDK for a running :class:`HTTPActionServer`."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        shared_secret: str | None = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        verify_loopback: bool = False,
+    ) -> None:
+        stripped = base_url.rstrip("/")
+        if not stripped:
+            raise HTTPActionClientException("base_url must be non-empty")
+        if verify_loopback:
+            validate_http_url(stripped)
+        self._base_url = stripped
+        self._shared_secret = shared_secret
+        self._timeout = float(timeout)
+        self._session = requests.Session()
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def execute(self, actions: list | dict) -> Any:
+        """POST ``actions`` to ``/actions`` and return the decoded JSON body."""
+        if not isinstance(actions, (list, dict)):
+            raise HTTPActionClientException(
+                f"actions must be list or dict, got {type(actions).__name__}"
+            )
+        url = f"{self._base_url}{_ACTIONS_PATH}"
+        headers = {"Content-Type": "application/json"}
+        if self._shared_secret:
+            headers["Authorization"] = f"Bearer {self._shared_secret}"
+        try:
+            response = self._session.post(
+                url,
+                json=actions,
+                headers=headers,
+                timeout=self._timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException as err:
+            raise HTTPActionClientException(f"request to {url} failed: {err}") from err
+        return _decode_response(response)
+
+    def ping(self) -> bool:
+        """Best-effort reachability probe — returns True if the server responds."""
+        url = f"{self._base_url}{_ACTIONS_PATH}"
+        try:
+            response = self._session.request(
+                "OPTIONS", url, timeout=min(self._timeout, 5.0), allow_redirects=False
+            )
+        except requests.RequestException:
+            return False
+        # The server only handles POST /actions; OPTIONS yields 501 which
+        # still proves it's reachable. 401/403 also prove reachability.
+        return response.status_code < 500 or response.status_code == 501
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> HTTPActionClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+def _decode_response(response: requests.Response) -> Any:
+    status = response.status_code
+    if status == 401:
+        raise HTTPActionClientException("unauthorized: missing or invalid shared secret")
+    if status == 403:
+        body = _safe_body(response)
+        raise HTTPActionClientException(f"forbidden: {body}")
+    if status == 404:
+        raise HTTPActionClientException("server does not expose /actions")
+    if status >= 400:
+        body = _safe_body(response)
+        raise HTTPActionClientException(f"server returned HTTP {status}: {body}")
+    try:
+        return response.json()
+    except ValueError as err:
+        file_automation_logger.error("http_client: bad JSON response: %r", err)
+        raise HTTPActionClientException(f"server returned invalid JSON: {err}") from err
+
+
+def _safe_body(response: requests.Response) -> str:
+    try:
+        data = response.json()
+    except ValueError:
+        return response.text[:200]
+    if isinstance(data, dict) and "error" in data:
+        return str(data["error"])
+    return str(data)[:200]
diff --git a/tests/test_http_client.py b/tests/test_http_client.py
new file mode 100644
index 0000000..d8ff381
--- /dev/null
+++ b/tests/test_http_client.py
@@ -0,0 +1,120 @@
+"""Tests for :class:`HTTPActionClient`."""
+# pylint: disable=cyclic-import
+
+from __future__ import annotations
+
+import pytest
+
+from automation_file.client import HTTPActionClient, HTTPActionClientException
+from automation_file.core.action_executor import executor
+from automation_file.server.action_acl import ActionACL
+from automation_file.server.http_server import start_http_action_server
+
+
+def _ensure_echo_registered() -> None:
+    if "test_client_echo" not in executor.registry:
+        executor.registry.register("test_client_echo", lambda value: value)
+
+
+def _base_url(server) -> str:
+    host, port = server.server_address
+    return f"http://{host}:{port}"
+
+
+def test_client_executes_action_round_trip() -> None:
+    _ensure_echo_registered()
+    server = start_http_action_server(host="127.0.0.1", port=0)
+    try:
+        with HTTPActionClient(_base_url(server)) as client:
+            result = client.execute([["test_client_echo", {"value": "hello"}]])
+        assert isinstance(result, dict)
+        assert any(value == "hello" for value in result.values())
+    finally:
+        server.shutdown()
+
+
+def test_client_sends_bearer_token_when_configured() -> None:
+    _ensure_echo_registered()
+    server = start_http_action_server(host="127.0.0.1", port=0, shared_secret="topsecret")
+    try:
+        with HTTPActionClient(_base_url(server), shared_secret="topsecret") as client:
+            result = client.execute([["test_client_echo", {"value": 42}]])
+        assert any(value == 42 for value in result.values())
+    finally:
+        server.shutdown()
+
+
+def test_client_unauthorized_when_missing_secret() -> None:
+    _ensure_echo_registered()
+    server = start_http_action_server(host="127.0.0.1", port=0, shared_secret="topsecret")
+    try:
+        with (
+            HTTPActionClient(_base_url(server)) as client,
+            pytest.raises(HTTPActionClientException, match="unauthorized"),
+        ):
+            client.execute([["test_client_echo", {"value": 1}]])
+    finally:
+        server.shutdown()
+
+
+def test_client_forbidden_when_denied_by_acl() -> None:
+    _ensure_echo_registered()
+    acl = ActionACL.build(denied=["test_client_echo"])
+    server = start_http_action_server(host="127.0.0.1", port=0, action_acl=acl)
+    try:
+        with (
+            HTTPActionClient(_base_url(server)) as client,
+            pytest.raises(HTTPActionClientException, match="forbidden"),
+        ):
+            client.execute([["test_client_echo", {"value": 1}]])
+    finally:
+        server.shutdown()
+
+
+def test_client_rejects_bad_action_type() -> None:
+    client = HTTPActionClient("http://127.0.0.1:1")
+    try:
+        with pytest.raises(HTTPActionClientException, match="list or dict"):
+            client.execute("not-a-list")  # type: ignore[arg-type]
+    finally:
+        client.close()
+
+
+def test_client_requires_base_url() -> None:
+    with pytest.raises(HTTPActionClientException, match="non-empty"):
+        HTTPActionClient("")
+
+
+def test_client_connection_error_wraps_request_exception() -> None:
+    # Port 1 is unlikely to have a server — connect should fail quickly.
+    client = HTTPActionClient("http://127.0.0.1:1", timeout=1.0)
+    try:
+        with pytest.raises(HTTPActionClientException, match="failed"):
+            client.execute([["noop"]])
+    finally:
+        client.close()
+
+
+def test_client_ping_reaches_running_server() -> None:
+    _ensure_echo_registered()
+    server = start_http_action_server(host="127.0.0.1", port=0)
+    try:
+        with HTTPActionClient(_base_url(server)) as client:
+            assert client.ping() is True
+    finally:
+        server.shutdown()
+
+
+def test_client_ping_returns_false_for_dead_endpoint() -> None:
+    client = HTTPActionClient("http://127.0.0.1:1", timeout=1.0)
+    try:
+        assert client.ping() is False
+    finally:
+        client.close()
+
+
+def test_client_surfaces_via_facade() -> None:
+    import automation_file
+
+    assert automation_file.HTTPActionClient is HTTPActionClient
+    assert automation_file.HTTPActionClientException is HTTPActionClientException

From b50c066c10935d0114392a3568960243494b4720 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:36:42 +0800
Subject: [PATCH 33/38] Add AES-GCM file encryption (encrypt_file /
 decrypt_file)

---
 automation_file/__init__.py             |  12 ++
 automation_file/core/action_registry.py |   4 +-
 automation_file/core/crypto.py          | 174 ++++++++++++++++++++++++
 dev.toml                                |   1 +
 stable.toml                             |   1 +
 tests/test_crypto.py                    | 138 +++++++++++++++++++
 6 files changed, 329 insertions(+), 1 deletion(-)
 create mode 100644 automation_file/core/crypto.py
 create mode 100644 tests/test_crypto.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index 2e7e523..ce695b8 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -29,6 +29,13 @@
 )
 from automation_file.core.config import AutomationConfig, ConfigException
 from automation_file.core.config_watcher import ConfigWatcher
+from automation_file.core.crypto import (
+    CryptoException,
+    decrypt_file,
+    encrypt_file,
+    generate_key,
+    key_from_password,
+)
 from automation_file.core.dag_executor import execute_action_dag
 from automation_file.core.fim import IntegrityMonitor
 from automation_file.core.json_store import read_action_json, write_action_json
@@ -325,6 +332,11 @@ def __getattr__(name: str) -> Any:
     "AuditException",
     "AuditLog",
     "IntegrityMonitor",
+    "CryptoException",
+    "encrypt_file",
+    "decrypt_file",
+    "generate_key",
+    "key_from_password",
     # Triggers
     "FileWatcher",
     "TriggerManager",
diff --git a/automation_file/core/action_registry.py b/automation_file/core/action_registry.py
index f2ebcc9..bc11948 100644
--- a/automation_file/core/action_registry.py
+++ b/automation_file/core/action_registry.py
@@ -153,7 +153,7 @@ def _http_commands() -> dict[str, Command]:
 
 
 def _utils_commands() -> dict[str, Command]:
-    from automation_file.core import checksum, manifest
+    from automation_file.core import checksum, crypto, manifest
     from automation_file.remote import cross_backend
     from automation_file.utils import deduplicate, fast_find, grep, rotate
 
@@ -168,6 +168,8 @@ def _utils_commands() -> dict[str, Command]:
         "FA_grep": grep.grep_files,
         "FA_rotate_backups": rotate.rotate_backups,
         "FA_copy_between": cross_backend.copy_between,
+        "FA_encrypt_file": crypto.encrypt_file,
+        "FA_decrypt_file": crypto.decrypt_file,
     }
 
 
diff --git a/automation_file/core/crypto.py b/automation_file/core/crypto.py
new file mode 100644
index 0000000..1a9573e
--- /dev/null
+++ b/automation_file/core/crypto.py
@@ -0,0 +1,174 @@
+"""AES-256-GCM file encryption helpers.
+
+``encrypt_file(source, target, key)`` writes a self-describing envelope::
+
+    magic    = b"FA-AESG"     7 bytes
+    version  = 0x01           1 byte
+    flags    = 0x00           1 byte (reserved)
+    aad_len  = uint32 BE      4 bytes
+    nonce    = 12 bytes
+    aad      = <aad_len>
+    ciphertext + tag          (rest — GCM tag is the trailing 16 bytes)
+
+``decrypt_file`` reads the same format, verifies the tag, and writes the
+plaintext to ``target``. Tampering (bit flips anywhere in the envelope
+except ``aad_len``) surfaces as :class:`CryptoException`.
+
+GCM has a hard plaintext limit of roughly 64 GiB per ``(key, nonce)``
+pair; since each encrypt generates a fresh nonce, the practical cap is
+per-file and is much larger than typical automation payloads. For files
+approaching that size, split before calling ``encrypt_file``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+from automation_file.exceptions import FileAutomationException
+from automation_file.logging_config import file_automation_logger
+
+_MAGIC = b"FA-AESG"
+_VERSION = 0x01
+_NONCE_SIZE = 12
+_HEADER_FIXED_SIZE = len(_MAGIC) + 2 + 4  # magic + version + flags + aad_len
+_VALID_KEY_SIZES = frozenset({16, 24, 32})
+_DEFAULT_PBKDF2_ITERATIONS = 200_000
+
+
+class CryptoException(FileAutomationException):
+    """Raised when encryption / decryption fails (including on tamper)."""
+
+
+def generate_key(*, bits: int = 256) -> bytes:
+    """Return cryptographically random bytes suitable for AES-GCM."""
+    if bits not in (128, 192, 256):
+        raise CryptoException(f"bits must be 128 / 192 / 256, got {bits}")
+    return os.urandom(bits // 8)
+
+
+def key_from_password(
+    password: str,
+    salt: bytes,
+    *,
+    iterations: int = _DEFAULT_PBKDF2_ITERATIONS,
+    bits: int = 256,
+) -> bytes:
+    """Derive a symmetric key from ``password`` via PBKDF2-HMAC-SHA256."""
+    if not password:
+        raise CryptoException("password must be non-empty")
+    if len(salt) < 16:
+        raise CryptoException("salt must be at least 16 bytes")
+    if bits not in (128, 192, 256):
+        raise CryptoException(f"bits must be 128 / 192 / 256, got {bits}")
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=bits // 8,
+        salt=salt,
+        iterations=iterations,
+    )
+    return kdf.derive(password.encode("utf-8"))
+
+
+def encrypt_file(
+    source: str | os.PathLike[str],
+    target: str | os.PathLike[str],
+    key: bytes,
+    *,
+    associated_data: bytes = b"",
+) -> dict[str, int]:
+    """Encrypt ``source`` to ``target`` under AES-GCM. Returns a size summary."""
+    _validate_key(key)
+    if not isinstance(associated_data, (bytes, bytearray)):
+        raise CryptoException("associated_data must be bytes")
+    src = Path(source)
+    if not src.is_file():
+        raise CryptoException(f"source file not found: {src}")
+
+    plaintext = src.read_bytes()
+    nonce = os.urandom(_NONCE_SIZE)
+    aesgcm = AESGCM(bytes(key))
+    ciphertext = aesgcm.encrypt(nonce, plaintext, bytes(associated_data) or None)
+
+    envelope = _build_header(associated_data, nonce) + ciphertext
+    dst = Path(target)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    dst.write_bytes(envelope)
+    file_automation_logger.info(
+        "encrypt_file: %s -> %s (%d -> %d bytes)",
+        src,
+        dst,
+        len(plaintext),
+        len(envelope),
+    )
+    return {"plaintext_bytes": len(plaintext), "ciphertext_bytes": len(envelope)}
+
+
+def decrypt_file(
+    source: str | os.PathLike[str],
+    target: str | os.PathLike[str],
+    key: bytes,
+) -> dict[str, int]:
+    """Decrypt ``source`` to ``target``. Raises on invalid tag / header."""
+    _validate_key(key)
+    src = Path(source)
+    if not src.is_file():
+        raise CryptoException(f"source file not found: {src}")
+    envelope = src.read_bytes()
+    nonce, aad, ciphertext = _parse_envelope(envelope)
+    aesgcm = AESGCM(bytes(key))
+    try:
+        plaintext = aesgcm.decrypt(nonce, ciphertext, aad or None)
+    except InvalidTag as err:
+        raise CryptoException("authentication failed: wrong key or tampered data") from err
+
+    dst = Path(target)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    dst.write_bytes(plaintext)
+    file_automation_logger.info(
+        "decrypt_file: %s -> %s (%d -> %d bytes)",
+        src,
+        dst,
+        len(envelope),
+        len(plaintext),
+    )
+    return {"ciphertext_bytes": len(envelope), "plaintext_bytes": len(plaintext)}
+
+
+def _validate_key(key: bytes) -> None:
+    if not isinstance(key, (bytes, bytearray)):
+        raise CryptoException("key must be bytes")
+    if len(key) not in _VALID_KEY_SIZES:
+        raise CryptoException(
+            f"key length must be 16 / 24 / 32 bytes, got {len(key)}",
+        )
+
+
+def _build_header(aad: bytes, nonce: bytes) -> bytes:
+    aad_len = len(aad).to_bytes(4, "big")
+    return _MAGIC + bytes([_VERSION, 0x00]) + aad_len + nonce + bytes(aad)
+
+
+def _parse_envelope(envelope: bytes) -> tuple[bytes, bytes, bytes]:
+    if len(envelope) < _HEADER_FIXED_SIZE + _NONCE_SIZE + 16:
+        raise CryptoException("ciphertext envelope is shorter than the fixed header")
+    if not envelope.startswith(_MAGIC):
+        raise CryptoException("not an AES-GCM envelope (bad magic)")
+    version = envelope[len(_MAGIC)]
+    if version != _VERSION:
+        raise CryptoException(f"unsupported envelope version {version}")
+    aad_len = int.from_bytes(envelope[_HEADER_FIXED_SIZE - 4 : _HEADER_FIXED_SIZE], "big")
+    nonce_start = _HEADER_FIXED_SIZE
+    nonce_end = nonce_start + _NONCE_SIZE
+    aad_end = nonce_end + aad_len
+    if aad_end > len(envelope):
+        raise CryptoException("envelope truncated before aad end")
+    nonce = envelope[nonce_start:nonce_end]
+    aad = envelope[nonce_end:aad_end]
+    ciphertext = envelope[aad_end:]
+    return nonce, aad, ciphertext
diff --git a/dev.toml b/dev.toml
index acf164d..55f49b4 100644
--- a/dev.toml
+++ b/dev.toml
@@ -25,6 +25,7 @@ dependencies = [
     "paramiko>=3.4.0",
     "PySide6>=6.6.0",
     "watchdog>=4.0.0",
+    "cryptography>=42.0.0",
     "tomli>=2.0.1; python_version<\"3.11\""
 ]
 classifiers = [
diff --git a/stable.toml b/stable.toml
index a0951fd..1c76553 100644
--- a/stable.toml
+++ b/stable.toml
@@ -25,6 +25,7 @@ dependencies = [
     "paramiko>=3.4.0",
     "PySide6>=6.6.0",
     "watchdog>=4.0.0",
+    "cryptography>=42.0.0",
     "tomli>=2.0.1; python_version<\"3.11\""
 ]
 classifiers = [
diff --git a/tests/test_crypto.py b/tests/test_crypto.py
new file mode 100644
index 0000000..53612a0
--- /dev/null
+++ b/tests/test_crypto.py
@@ -0,0 +1,138 @@
+"""Tests for AES-GCM file encryption helpers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from automation_file import (
+    CryptoException,
+    build_default_registry,
+    decrypt_file,
+    encrypt_file,
+    generate_key,
+    key_from_password,
+)
+
+
+def test_generate_key_default_length() -> None:
+    assert len(generate_key()) == 32
+
+
+def test_generate_key_rejects_bad_size() -> None:
+    with pytest.raises(CryptoException):
+        generate_key(bits=111)
+
+
+def test_round_trip_preserves_plaintext(tmp_path: Path) -> None:
+    key = generate_key()
+    source = tmp_path / "plain.bin"
+    source.write_bytes(b"top-secret payload\n")
+    enc = tmp_path / "cipher.bin"
+    dec = tmp_path / "restored.bin"
+    summary = encrypt_file(source, enc, key)
+    assert summary["plaintext_bytes"] == source.stat().st_size
+    decrypt_file(enc, dec, key)
+    assert dec.read_bytes() == source.read_bytes()
+
+
+def test_ciphertext_differs_between_calls(tmp_path: Path) -> None:
+    key = generate_key()
+    source = tmp_path / "plain.bin"
+    source.write_bytes(b"same data")
+    enc_a = tmp_path / "a.bin"
+    enc_b = tmp_path / "b.bin"
+    encrypt_file(source, enc_a, key)
+    encrypt_file(source, enc_b, key)
+    assert enc_a.read_bytes() != enc_b.read_bytes()
+
+
+def test_wrong_key_fails(tmp_path: Path) -> None:
+    good = generate_key()
+    bad = generate_key()
+    source = tmp_path / "plain.bin"
+    source.write_bytes(b"x" * 128)
+    enc = tmp_path / "cipher.bin"
+    encrypt_file(source, enc, good)
+    with pytest.raises(CryptoException, match="authentication"):
+        decrypt_file(enc, tmp_path / "dec.bin", bad)
+
+
+def test_tampered_ciphertext_fails(tmp_path: Path) -> None:
+    key = generate_key()
+    source = tmp_path / "plain.bin"
+    source.write_bytes(b"x" * 128)
+    enc = tmp_path / "cipher.bin"
+    encrypt_file(source, enc, key)
+    contents = bytearray(enc.read_bytes())
+    contents[-1] ^= 0x01
+    enc.write_bytes(bytes(contents))
+    with pytest.raises(CryptoException, match="authentication"):
+        decrypt_file(enc, tmp_path / "dec.bin", key)
+
+
+def test_associated_data_roundtrip(tmp_path: Path) -> None:
+    key = generate_key()
+    source = tmp_path / "plain.bin"
+    source.write_bytes(b"hello")
+    enc = tmp_path / "cipher.bin"
+    encrypt_file(source, enc, key, associated_data=b"file=plain.bin")
+    dec = tmp_path / "dec.bin"
+    decrypt_file(enc, dec, key)
+    assert dec.read_bytes() == b"hello"
+
+
+def test_invalid_key_size(tmp_path: Path) -> None:
+    source = tmp_path / "plain.bin"
+    source.write_bytes(b"x")
+    with pytest.raises(CryptoException, match="key length"):
+        encrypt_file(source, tmp_path / "out", b"\x00" * 10)
+
+
+def test_missing_source_raises(tmp_path: Path) -> None:
+    with pytest.raises(CryptoException, match="source file"):
+        encrypt_file(tmp_path / "absent", tmp_path / "out", generate_key())
+
+
+def test_bad_magic_rejected(tmp_path: Path) -> None:
+    garbage = tmp_path / "junk.bin"
+    garbage.write_bytes(b"NOT-A-REAL-ENVELOPE" + b"\x00" * 64)
+    with pytest.raises(CryptoException, match="magic"):
+        decrypt_file(garbage, tmp_path / "out.bin", generate_key())
+
+
+def test_key_from_password_deterministic() -> None:
+    salt = b"\x00" * 16
+    key_a = key_from_password("passphrase", salt, iterations=1_000)
+    key_b = key_from_password("passphrase", salt, iterations=1_000)
+    assert key_a == key_b
+    assert len(key_a) == 32
+
+
+def test_key_from_password_requires_nonempty_password() -> None:
+    with pytest.raises(CryptoException, match="non-empty"):
+        key_from_password("", b"\x00" * 16)
+
+
+def test_key_from_password_rejects_short_salt() -> None:
+    with pytest.raises(CryptoException, match="salt"):
+        key_from_password("pw", b"\x00" * 8)
+
+
+def test_key_from_password_round_trip(tmp_path: Path) -> None:
+    salt = b"sixteen-byte-saltX"
+    key = key_from_password("strong-password", salt, iterations=1_000)
+    source = tmp_path / "plain.txt"
+    source.write_text("hello", encoding="utf-8")
+    enc = tmp_path / "cipher.bin"
+    encrypt_file(source, enc, key)
+    dec = tmp_path / "dec.txt"
+    decrypt_file(enc, dec, key)
+    assert dec.read_text(encoding="utf-8") == "hello"
+
+
+def test_encrypt_decrypt_actions_registered() -> None:
+    registry = build_default_registry()
+    assert "FA_encrypt_file" in registry
+    assert "FA_decrypt_file" in registry

From 7304b1b09edfb3e41a94cfae9b30d029827e0d42 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:40:11 +0800
Subject: [PATCH 34/38] Add Prometheus metrics exporter for action execution

---
 automation_file/__init__.py              |  9 +++
 automation_file/core/action_executor.py  | 43 ++++++++---
 automation_file/core/metrics.py          | 65 ++++++++++++++++
 automation_file/server/metrics_server.py | 67 +++++++++++++++++
 dev.toml                                 |  1 +
 stable.toml                              |  1 +
 tests/test_metrics.py                    | 95 ++++++++++++++++++++++++
 7 files changed, 270 insertions(+), 11 deletions(-)
 create mode 100644 automation_file/core/metrics.py
 create mode 100644 automation_file/server/metrics_server.py
 create mode 100644 tests/test_metrics.py

diff --git a/automation_file/__init__.py b/automation_file/__init__.py
index ce695b8..3a620d1 100644
--- a/automation_file/__init__.py
+++ b/automation_file/__init__.py
@@ -40,6 +40,8 @@
 from automation_file.core.fim import IntegrityMonitor
 from automation_file.core.json_store import read_action_json, write_action_json
 from automation_file.core.manifest import ManifestException, verify_manifest, write_manifest
+from automation_file.core.metrics import ACTION_COUNT, ACTION_DURATION, record_action
+from automation_file.core.metrics import render as render_metrics
 from automation_file.core.package_loader import PackageLoader
 from automation_file.core.progress import (
     CancellationToken,
@@ -169,6 +171,7 @@
 )
 from automation_file.server.action_acl import ActionACL, ActionNotPermittedException
 from automation_file.server.http_server import HTTPActionServer, start_http_action_server
+from automation_file.server.metrics_server import MetricsServer, start_metrics_server
 from automation_file.server.tcp_server import (
     TCPActionServer,
     start_autocontrol_socket_server,
@@ -337,6 +340,12 @@ def __getattr__(name: str) -> Any:
     "decrypt_file",
     "generate_key",
     "key_from_password",
+    "ACTION_COUNT",
+    "ACTION_DURATION",
+    "record_action",
+    "render_metrics",
+    "MetricsServer",
+    "start_metrics_server",
     # Triggers
     "FileWatcher",
     "TriggerManager",
diff --git a/automation_file/core/action_executor.py b/automation_file/core/action_executor.py
index e50abd5..f9aadad 100644
--- a/automation_file/core/action_executor.py
+++ b/automation_file/core/action_executor.py
@@ -15,12 +15,14 @@
 
 from __future__ import annotations
 
+import time
 from collections.abc import Mapping
 from concurrent.futures import ThreadPoolExecutor
 from typing import Any
 
 from automation_file.core.action_registry import ActionRegistry, build_default_registry
 from automation_file.core.json_store import read_action_json
+from automation_file.core.metrics import record_action
 from automation_file.core.substitution import substitute as substitute_payload
 from automation_file.exceptions import ExecuteActionException, ValidationException
 from automation_file.logging_config import file_automation_logger
@@ -150,20 +152,15 @@ def add_command_to_executor(self, command_dict: Mapping[str, Any]) -> None:
 
     # Internals ---------------------------------------------------------
     def _run_one(self, action: list, dry_run: bool) -> Any:
+        name = _safe_action_name(action)
+        if dry_run:
+            return self._run_dry(action)
+        started = time.monotonic()
+        ok = False
         try:
-            if dry_run:
-                name, kind, payload = self._parse_action(action)
-                if self.registry.resolve(name) is None:
-                    raise ExecuteActionException(f"unknown action: {name!r}")
-                file_automation_logger.info(
-                    "dry_run: %s kind=%s payload=%r",
-                    name,
-                    kind,
-                    payload,
-                )
-                return f"dry_run:{name}"
             value = self._execute_event(action)
             file_automation_logger.info("execute_action: %s", action)
+            ok = True
             return value
         except ExecuteActionException as error:
             file_automation_logger.error("execute_action malformed: %r", error)
@@ -171,6 +168,24 @@ def _run_one(self, action: list, dry_run: bool) -> Any:
         except Exception as error:  # pylint: disable=broad-except
             file_automation_logger.error("execute_action runtime error: %r", error)
             return repr(error)
+        finally:
+            record_action(name, time.monotonic() - started, ok)
+
+    def _run_dry(self, action: list) -> Any:
+        try:
+            name, kind, payload = self._parse_action(action)
+            if self.registry.resolve(name) is None:
+                raise ExecuteActionException(f"unknown action: {name!r}")
+        except ExecuteActionException as error:
+            file_automation_logger.error("execute_action malformed: %r", error)
+            return repr(error)
+        file_automation_logger.info(
+            "dry_run: %s kind=%s payload=%r",
+            name,
+            kind,
+            payload,
+        )
+        return f"dry_run:{name}"
 
     @staticmethod
     def _coerce(action_list: list | Mapping[str, Any]) -> list:
@@ -188,6 +203,12 @@ def _coerce(action_list: list | Mapping[str, Any]) -> list:
         return action_list
 
 
+def _safe_action_name(action: Any) -> str:
+    if isinstance(action, list) and action and isinstance(action[0], str):
+        return action[0]
+    return "unknown"
+
+
 # Default shared executor — built once, mutated in place by plugins.
 executor: ActionExecutor = ActionExecutor()
 
diff --git a/automation_file/core/metrics.py b/automation_file/core/metrics.py
new file mode 100644
index 0000000..f9d7c7f
--- /dev/null
+++ b/automation_file/core/metrics.py
@@ -0,0 +1,65 @@
+"""Prometheus metrics — per-action counters and duration histogram.
+
+The module exposes two metrics that are updated from
+:class:`~automation_file.core.action_executor.ActionExecutor` on every
+call:
+
+* ``automation_file_actions_total{action, status}`` — counter incremented
+  with ``status="ok"`` or ``status="error"`` per action.
+* ``automation_file_action_duration_seconds{action}`` — histogram of wall
+  time spent inside the registered callable.
+
+:func:`render` returns the wire-format text and matching ``Content-Type``
+suitable for a ``GET /metrics`` handler. :func:`record_action` is the
+single write path — failures are swallowed so a broken metrics backend
+can never abort a real action.
+"""
+
+from __future__ import annotations
+
+from prometheus_client import CONTENT_TYPE_LATEST, REGISTRY, Counter, Histogram, generate_latest
+
+from automation_file.logging_config import file_automation_logger
+
+_DURATION_BUCKETS = (
+    0.005,
+    0.01,
+    0.025,
+    0.05,
+    0.1,
+    0.25,
+    0.5,
+    1.0,
+    2.5,
+    5.0,
+    10.0,
+    30.0,
+    60.0,
+)
+
+ACTION_COUNT = Counter(
+    "automation_file_actions_total",
+    "Total actions executed, partitioned by outcome.",
+    labelnames=("action", "status"),
+)
+ACTION_DURATION = Histogram(
+    "automation_file_action_duration_seconds",
+    "Time spent inside a registered action callable.",
+    labelnames=("action",),
+    buckets=_DURATION_BUCKETS,
+)
+
+
+def record_action(action: str, duration_seconds: float, ok: bool) -> None:
+    """Record one action execution. Never raises."""
+    status = "ok" if ok else "error"
+    try:
+        ACTION_COUNT.labels(action=action, status=status).inc()
+        ACTION_DURATION.labels(action=action).observe(max(0.0, float(duration_seconds)))
+    except Exception as err:  # pragma: no cover - defensive
+        file_automation_logger.error("metrics.record_action failed: %r", err)
+
+
+def render() -> tuple[bytes, str]:
+    """Return ``(payload, content_type)`` for a ``/metrics`` response."""
+    return generate_latest(REGISTRY), CONTENT_TYPE_LATEST
diff --git a/automation_file/server/metrics_server.py b/automation_file/server/metrics_server.py
new file mode 100644
index 0000000..779d7db
--- /dev/null
+++ b/automation_file/server/metrics_server.py
@@ -0,0 +1,67 @@
+"""Prometheus scrape endpoint (``GET /metrics``).
+
+``start_metrics_server(host, port)`` spawns a threaded HTTP server that
+serves the current metrics snapshot rendered by
+:func:`automation_file.core.metrics.render`. Like the other servers in
+this package it defaults to loopback and requires ``allow_non_loopback=True``
+to bind elsewhere. No auth is attached by default — put it behind a
+reverse proxy or use an ACL at the network layer if exposing beyond a
+trusted host.
+"""
+
+from __future__ import annotations
+
+import threading
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from automation_file.core.metrics import render
+from automation_file.logging_config import file_automation_logger
+from automation_file.server.network_guards import ensure_loopback
+
+_DEFAULT_HOST = "127.0.0.1"
+_DEFAULT_PORT = 9945
+_METRICS_PATH = "/metrics"
+
+
+class _MetricsHandler(BaseHTTPRequestHandler):
+    """GET /metrics -> current Prometheus snapshot."""
+
+    def log_message(  # pylint: disable=arguments-differ
+        self, format_str: str, *args: object
+    ) -> None:
+        file_automation_logger.info("metrics_server: " + format_str, *args)
+
+    def do_GET(self) -> None:  # pylint: disable=invalid-name — BaseHTTPRequestHandler API
+        if self.path != _METRICS_PATH:
+            self._send(HTTPStatus.NOT_FOUND, b"not found", "text/plain; charset=utf-8")
+            return
+        payload, content_type = render()
+        self._send(HTTPStatus.OK, payload, content_type)
+
+    def _send(self, status: HTTPStatus, payload: bytes, content_type: str) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+
+class MetricsServer(ThreadingHTTPServer):
+    """Threaded HTTP server serving ``GET /metrics``."""
+
+
+def start_metrics_server(
+    host: str = _DEFAULT_HOST,
+    port: int = _DEFAULT_PORT,
+    allow_non_loopback: bool = False,
+) -> MetricsServer:
+    """Start a metrics server on a background thread and return it."""
+    if not allow_non_loopback:
+        ensure_loopback(host)
+    server = MetricsServer((host, port), _MetricsHandler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    address = server.server_address
+    file_automation_logger.info("metrics_server: listening on %s:%d", address[0], address[1])
+    return server
diff --git a/dev.toml b/dev.toml
index 55f49b4..75f99e2 100644
--- a/dev.toml
+++ b/dev.toml
@@ -26,6 +26,7 @@ dependencies = [
     "PySide6>=6.6.0",
     "watchdog>=4.0.0",
     "cryptography>=42.0.0",
+    "prometheus_client>=0.20.0",
     "tomli>=2.0.1; python_version<\"3.11\""
 ]
 classifiers = [
diff --git a/stable.toml b/stable.toml
index 1c76553..04e1f4c 100644
--- a/stable.toml
+++ b/stable.toml
@@ -26,6 +26,7 @@ dependencies = [
     "PySide6>=6.6.0",
     "watchdog>=4.0.0",
     "cryptography>=42.0.0",
+    "prometheus_client>=0.20.0",
     "tomli>=2.0.1; python_version<\"3.11\""
 ]
 classifiers = [
diff --git a/tests/test_metrics.py b/tests/test_metrics.py
new file mode 100644
index 0000000..fcb1b6d
--- /dev/null
+++ b/tests/test_metrics.py
@@ -0,0 +1,95 @@
+"""Tests for the Prometheus metrics exporter."""
+
+from __future__ import annotations
+
+import urllib.request
+
+import pytest
+
+from automation_file import (
+    ACTION_COUNT,
+    execute_action,
+    record_action,
+    render_metrics,
+    start_metrics_server,
+)
+from automation_file.core.action_executor import executor
+from tests._insecure_fixtures import insecure_url, ipv4
+
+
+def _register_probes() -> None:
+    if "test_metric_ok" not in executor.registry:
+        executor.registry.register("test_metric_ok", lambda: "ok")
+    if "test_metric_fail" not in executor.registry:
+
+        def _boom() -> None:
+            raise RuntimeError("boom")
+
+        executor.registry.register("test_metric_fail", _boom)
+
+
+def test_record_action_increments_counter() -> None:
+    before = ACTION_COUNT.labels(action="unit.test", status="ok")._value.get()
+    record_action("unit.test", 0.01, ok=True)
+    after = ACTION_COUNT.labels(action="unit.test", status="ok")._value.get()
+    assert after == before + 1
+
+
+def test_record_action_clamps_negative_duration() -> None:
+    # Must not raise.
+    record_action("unit.clamp", -5.0, ok=True)
+
+
+def test_render_metrics_content_type() -> None:
+    payload, content_type = render_metrics()
+    assert content_type.startswith("text/plain")
+    assert b"automation_file_actions_total" in payload
+
+
+def test_execute_action_increments_ok_counter() -> None:
+    _register_probes()
+    before = ACTION_COUNT.labels(action="test_metric_ok", status="ok")._value.get()
+    execute_action([["test_metric_ok"]])
+    after = ACTION_COUNT.labels(action="test_metric_ok", status="ok")._value.get()
+    assert after == before + 1
+
+
+def test_execute_action_increments_error_counter() -> None:
+    _register_probes()
+    before = ACTION_COUNT.labels(action="test_metric_fail", status="error")._value.get()
+    execute_action([["test_metric_fail"]])
+    after = ACTION_COUNT.labels(action="test_metric_fail", status="error")._value.get()
+    assert after == before + 1
+
+
+def test_metrics_server_serves_metrics_endpoint() -> None:
+    _register_probes()
+    execute_action([["test_metric_ok"]])
+    server = start_metrics_server(host="127.0.0.1", port=0)
+    host, port = server.server_address
+    try:
+        url = insecure_url("http", f"{host}:{port}/metrics")
+        with urllib.request.urlopen(url, timeout=3) as resp:  # nosec B310 - loopback test server
+            body = resp.read().decode("utf-8")
+        assert resp.status == 200
+        assert "automation_file_actions_total" in body
+    finally:
+        server.shutdown()
+
+
+def test_metrics_server_returns_404_for_other_paths() -> None:
+    server = start_metrics_server(host="127.0.0.1", port=0)
+    host, port = server.server_address
+    try:
+        url = insecure_url("http", f"{host}:{port}/other")
+        with pytest.raises(urllib.error.HTTPError) as info:
+            urllib.request.urlopen(url, timeout=3)  # nosec B310 - loopback test server
+        assert info.value.code == 404
+    finally:
+        server.shutdown()
+
+
+def test_metrics_server_rejects_non_loopback() -> None:
+    non_loopback = ipv4(8, 8, 8, 8)
+    with pytest.raises(ValueError):
+        start_metrics_server(host=non_loopback, port=0)

From e90bbd3c9135d7586fd46cb8419441a15819d575 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:47:12 +0800
Subject: [PATCH 35/38] Document new features across READMEs and Sphinx API
 docs

---
 README.md                  | 127 ++++++++++++++++++++++++++++++++++++-
 README.zh-CN.md            | 124 +++++++++++++++++++++++++++++++++++-
 README.zh-TW.md            | 124 +++++++++++++++++++++++++++++++++++-
 docs/source/api/client.rst |   5 ++
 docs/source/api/core.rst   |  18 ++++++
 docs/source/api/index.rst  |   1 +
 docs/source/api/local.rst  |  12 ++++
 docs/source/api/remote.rst |  28 ++++++++
 docs/source/api/server.rst |   6 ++
 9 files changed, 442 insertions(+), 3 deletions(-)
 create mode 100644 docs/source/api/client.rst

diff --git a/README.md b/README.md
index ecf3e7e..edc387b 100644
--- a/README.md
+++ b/README.md
@@ -27,8 +27,21 @@ facade.
 - **Entry-point plugins** — third-party packages register their own `FA_*` actions via `[project.entry-points."automation_file.actions"]`; `build_default_registry()` picks them up automatically
 - **Incremental directory sync** — rsync-style mirror with size+mtime or checksum change detection, optional delete of extras, dry-run (`FA_sync_dir`)
 - **Directory manifests** — JSON snapshot of every file's checksum under a root, with separate missing/modified/extra reporting on verify (`FA_write_manifest`, `FA_verify_manifest`)
-- **Notification sinks** — webhook / Slack / SMTP with a fanout manager that does per-sink error isolation and sliding-window dedup; auto-notify on trigger + scheduler failures (`FA_notify_send`, `FA_notify_list`)
+- **Notification sinks** — webhook / Slack / SMTP / Telegram / Discord / Teams / PagerDuty with a fanout manager that does per-sink error isolation and sliding-window dedup; auto-notify on trigger + scheduler failures (`FA_notify_send`, `FA_notify_list`)
 - **Config file + secret providers** — declare notification sinks / defaults in `automation_file.toml`; `${env:…}` and `${file:…}` references resolve through an Env/File/Chained provider abstraction so secrets stay out of the file itself
+- **Config hot reload** — `ConfigWatcher` polls `automation_file.toml` and re-applies sinks / defaults on change without restart
+- **Shell / grep / JSON edit / tar / backup rotation** — `FA_run_shell` (argument-list subprocess with timeout), `FA_grep` (streaming text search), `FA_json_get` / `FA_json_set` / `FA_json_delete` (in-place JSON editing), `FA_create_tar` / `FA_extract_tar`, `FA_rotate_backups`
+- **FTP / FTPS backend** — plain FTP or explicit FTPS via `FTP_TLS.auth()`; auto-registered as `FA_ftp_*`
+- **Cross-backend copy** — `FA_copy_between` moves data between any two backends via `local://`, `s3://`, `drive://`, `azure://`, `dropbox://`, `sftp://`, `ftp://` URIs
+- **Scheduler overlap guard** — running jobs are skipped on the next fire unless `allow_overlap=True`
+- **Server action ACL** — `allowed_actions=(...)` restricts which commands TCP / HTTP servers will dispatch
+- **Variable substitution** — opt-in `${env:VAR}` / `${date:%Y-%m-%d}` / `${uuid}` / `${cwd}` expansion in action arguments via `execute_action(..., substitute=True)`
+- **Conditional execution** — `FA_if_exists` / `FA_if_newer` / `FA_if_size_gt` run a nested action list only when a guard passes
+- **SQLite audit log** — `AuditLog(db_path)` records every action execution with actor / status / duration; query via `recent` / `count` / `purge`
+- **File integrity monitor** — `IntegrityMonitor` polls a tree against a manifest and fires a callback + notification on drift
+- **HTTPActionClient SDK** — typed Python client for the HTTP action server with shared-secret auth, loopback guard, and OPTIONS-based ping
+- **AES-256-GCM file encryption** — `encrypt_file` / `decrypt_file` with `generate_key()` / `key_from_password()` (PBKDF2-HMAC-SHA256); JSON actions `FA_encrypt_file` / `FA_decrypt_file`
+- **Prometheus metrics exporter** — `start_metrics_server()` exposes `automation_file_actions_total{action,status}` counters and `automation_file_action_duration_seconds{action}` histograms
 - PySide6 GUI (`python -m automation_file ui`) with a tab per backend, the JSON-action runner, and dedicated tabs for Triggers, Scheduler, and live Progress
 - Rich CLI with one-shot subcommands plus legacy JSON-batch flags
 - Project scaffolding (`ProjectBuilder`) for executor-based automations
@@ -499,6 +512,118 @@ silently becoming empty strings. Custom provider chains can be built from
 `ChainedSecretProvider` / `EnvSecretProvider` / `FileSecretProvider` and
 passed as `AutomationConfig.load(path, provider=…)`.
 
+### Variable substitution in action lists
+Opt in with `substitute=True` and `${…}` references expand at dispatch time:
+
+```python
+from automation_file import execute_action
+
+execute_action(
+    [["FA_create_file", {"file_path": "reports/${date:%Y-%m-%d}/${uuid}.txt"}]],
+    substitute=True,
+)
+```
+
+Supports `${env:VAR}`, `${date:FMT}` (strftime), `${uuid}`, `${cwd}`. Unknown
+names raise `SubstitutionException` — no silent empty strings.
+
+### Conditional execution
+Run a nested action list only when a path-based guard passes:
+
+```json
+[
+  ["FA_if_exists", {"path": "/data/in/job.json",
+                    "then": [["FA_copy_file", {"source": "/data/in/job.json",
+                                               "target": "/data/processed/job.json"}]]}],
+  ["FA_if_newer",  {"source": "/src", "target": "/dst",
+                    "then": [["FA_sync_dir", {"src": "/src", "dst": "/dst"}]]}],
+  ["FA_if_size_gt", {"path": "/logs/app.log", "size": 10485760,
+                     "then": [["FA_run_shell", {"command": ["logrotate", "/logs/app.log"]}]]}]
+]
+```
+
+### SQLite audit log
+`AuditLog` writes one row per action with short-lived connections and a
+module-level lock:
+
+```python
+from automation_file import AuditLog
+
+audit = AuditLog("audit.sqlite3")
+audit.record(action="FA_copy_file", actor="ops",
+             status="ok", duration_ms=12, detail={"src": "a", "dst": "b"})
+
+for row in audit.recent(limit=50):
+    print(row["timestamp"], row["action"], row["status"])
+```
+
+### File integrity monitor
+Poll a tree against a manifest and fire a callback + notification on drift:
+
+```python
+from automation_file import IntegrityMonitor, notification_manager, write_manifest
+
+write_manifest("/srv/site", "/srv/MANIFEST.json")
+
+mon = IntegrityMonitor(
+    root="/srv/site",
+    manifest_path="/srv/MANIFEST.json",
+    interval=60.0,
+    manager=notification_manager,
+    on_drift=lambda summary: print("drift:", summary),
+)
+mon.start()
+```
+
+Manifest-load errors are surfaced as drift so tamper and config issues
+aren't silently different code paths.
+
+### AES-256-GCM file encryption
+Authenticated encryption with a self-describing envelope. Derive a key from
+a password or generate one directly:
+
+```python
+from automation_file import encrypt_file, decrypt_file, key_from_password
+
+key = key_from_password("correct horse battery staple", salt=b"app-salt-v1")
+encrypt_file("secret.pdf", "secret.pdf.enc", key, associated_data=b"v1")
+decrypt_file("secret.pdf.enc", "secret.pdf", key, associated_data=b"v1")
+```
+
+Tamper is detected via GCM's authentication tag and reported as
+`CryptoException("authentication failed")`. JSON actions:
+`FA_encrypt_file`, `FA_decrypt_file`.
+
+### HTTPActionClient Python SDK
+Typed client for the HTTP action server; enforces loopback by default and
+carries the shared secret for you:
+
+```python
+from automation_file import HTTPActionClient
+
+with HTTPActionClient("http://127.0.0.1:9944", shared_secret="s3cr3t") as client:
+    client.ping()                                       # OPTIONS /actions
+    result = client.execute([["FA_create_dir", {"dir_path": "x"}]])
+```
+
+Auth failures map to `HTTPActionClientException` with `kind="unauthorized"`;
+404 responses report the server exists but does not expose `/actions`.
+
+### Prometheus metrics exporter
+`ActionExecutor` records one counter row and one histogram sample per
+action. Serve them on a loopback `/metrics` endpoint:
+
+```python
+from automation_file import start_metrics_server
+
+server = start_metrics_server(host="127.0.0.1", port=9945)
+# curl http://127.0.0.1:9945/metrics
+```
+
+Exports `automation_file_actions_total{action,status}` and
+`automation_file_action_duration_seconds{action}`. Non-loopback binds
+require `allow_non_loopback=True` explicitly.
+
 ### DAG action executor
 Run actions in dependency order; independent branches fan out across a
 thread pool. Each node is `{"id": ..., "action": [...], "depends_on":
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 0fd51a6..c0ae731 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -25,8 +25,21 @@ TCP / HTTP 服务器执行的 JSON 驱动动作。内附 PySide6 GUI，每个功
 - **Entry-point 插件** — 第三方包通过 `[project.entry-points."automation_file.actions"]` 注册自定义 `FA_*` 动作；`build_default_registry()` 会自动加载
 - **增量目录同步** — rsync 风格镜像，支持 size+mtime 或 checksum 变更检测，可选删除多余文件，支持干跑（`FA_sync_dir`）
 - **目录 manifest** — 以 JSON 快照记录树下每个文件的校验和，验证时分开报告 missing / modified / extra（`FA_write_manifest`、`FA_verify_manifest`）
-- **通知 sink** — webhook / Slack / SMTP，fanout 管理器做单 sink 错误隔离与滑动窗口去重；trigger + scheduler 失败时自动通知（`FA_notify_send`、`FA_notify_list`）
+- **通知 sink** — webhook / Slack / SMTP / Telegram / Discord / Teams / PagerDuty，fanout 管理器做单 sink 错误隔离与滑动窗口去重；trigger + scheduler 失败时自动通知（`FA_notify_send`、`FA_notify_list`）
 - **配置文件 + 密钥提供者** — 在 `automation_file.toml` 声明通知 sink / 默认值；`${env:…}` 与 `${file:…}` 引用通过 Env / File / Chained 提供者抽象解析，让密钥不留在配置文件中
+- **配置热加载** — `ConfigWatcher` 轮询 `automation_file.toml`，变更时即时应用 sink / 默认值,无需重启
+- **Shell / grep / JSON 编辑 / tar / 备份轮转** — `FA_run_shell`(参数列表式 subprocess,含超时)、`FA_grep`(流式文本搜索)、`FA_json_get` / `FA_json_set` / `FA_json_delete`(原地 JSON 编辑)、`FA_create_tar` / `FA_extract_tar`、`FA_rotate_backups`
+- **FTP / FTPS 后端** — 纯 FTP 或通过 `FTP_TLS.auth()` 的显式 FTPS;自动注册为 `FA_ftp_*`
+- **跨后端复制** — `FA_copy_between` 通过 `local://`、`s3://`、`drive://`、`azure://`、`dropbox://`、`sftp://`、`ftp://` URI 在任意两个后端之间搬运数据
+- **调度器重叠防护** — 正在执行的作业在下次触发时会被跳过,除非显式传入 `allow_overlap=True`
+- **服务器动作 ACL** — `allowed_actions=(...)` 限制 TCP / HTTP 服务器可派发的命令
+- **变量替换** — 动作参数中可选使用 `${env:VAR}` / `${date:%Y-%m-%d}` / `${uuid}` / `${cwd}`,通过 `execute_action(..., substitute=True)` 展开
+- **条件执行** — `FA_if_exists` / `FA_if_newer` / `FA_if_size_gt` 仅在路径守卫通过时执行嵌套动作清单
+- **SQLite 审计日志** — `AuditLog(db_path)` 为每个动作记录 actor / status / duration;通过 `recent` / `count` / `purge` 查询
+- **文件完整性监控** — `IntegrityMonitor` 按 manifest 轮询整棵树,检测到 drift 时触发 callback + 通知
+- **HTTPActionClient SDK** — HTTP 动作服务器的类型化 Python 客户端,具 shared-secret 认证、loopback 守护与 OPTIONS ping
+- **AES-256-GCM 文件加密** — `encrypt_file` / `decrypt_file` 搭配 `generate_key()` / `key_from_password()`(PBKDF2-HMAC-SHA256);JSON 动作 `FA_encrypt_file` / `FA_decrypt_file`
+- **Prometheus metrics 导出器** — `start_metrics_server()` 提供 `automation_file_actions_total{action,status}` 计数器与 `automation_file_action_duration_seconds{action}` 直方图
 - PySide6 GUI（`python -m automation_file ui`）每个后端一个页签，含 JSON 动作执行器，另有 Triggers、Scheduler、实时 Progress 专属页签
 - 功能丰富的 CLI，包含一次性子命令与旧式 JSON 批量标志
 - 项目脚手架（`ProjectBuilder`）协助构建以 executor 为核心的自动化项目
@@ -489,6 +502,115 @@ config.apply_to(notification_manager)
 `FileSecretProvider` 构建自定义提供者链，并以
 `AutomationConfig.load(path, provider=…)` 传入。
 
+### 动作清单变量替换
+以 `substitute=True` 启用后,`${…}` 引用会在派发时展开:
+
+```python
+from automation_file import execute_action
+
+execute_action(
+    [["FA_create_file", {"file_path": "reports/${date:%Y-%m-%d}/${uuid}.txt"}]],
+    substitute=True,
+)
+```
+
+支持 `${env:VAR}`、`${date:FMT}`(strftime)、`${uuid}`、`${cwd}`。未知名称
+会抛出 `SubstitutionException`,不会默默变成空字符串。
+
+### 条件执行
+只在路径守卫通过时执行嵌套动作清单:
+
+```json
+[
+  ["FA_if_exists", {"path": "/data/in/job.json",
+                    "then": [["FA_copy_file", {"source": "/data/in/job.json",
+                                               "target": "/data/processed/job.json"}]]}],
+  ["FA_if_newer",  {"source": "/src", "target": "/dst",
+                    "then": [["FA_sync_dir", {"src": "/src", "dst": "/dst"}]]}],
+  ["FA_if_size_gt", {"path": "/logs/app.log", "size": 10485760,
+                     "then": [["FA_run_shell", {"command": ["logrotate", "/logs/app.log"]}]]}]
+]
+```
+
+### SQLite 审计日志
+`AuditLog` 以短连接 + 模块级锁为每个动作写入一条记录:
+
+```python
+from automation_file import AuditLog
+
+audit = AuditLog("audit.sqlite3")
+audit.record(action="FA_copy_file", actor="ops",
+             status="ok", duration_ms=12, detail={"src": "a", "dst": "b"})
+
+for row in audit.recent(limit=50):
+    print(row["timestamp"], row["action"], row["status"])
+```
+
+### 文件完整性监控
+按 manifest 轮询整棵树,检测到 drift 时触发 callback + 通知:
+
+```python
+from automation_file import IntegrityMonitor, notification_manager, write_manifest
+
+write_manifest("/srv/site", "/srv/MANIFEST.json")
+
+mon = IntegrityMonitor(
+    root="/srv/site",
+    manifest_path="/srv/MANIFEST.json",
+    interval=60.0,
+    manager=notification_manager,
+    on_drift=lambda summary: print("drift:", summary),
+)
+mon.start()
+```
+
+加载 manifest 时的错误也会被视为 drift,让篡改与配置问题走同一条处理
+路径。
+
+### AES-256-GCM 文件加密
+带认证的加密与自描述封包格式。可由密码派生密钥或直接生成密钥:
+
+```python
+from automation_file import encrypt_file, decrypt_file, key_from_password
+
+key = key_from_password("correct horse battery staple", salt=b"app-salt-v1")
+encrypt_file("secret.pdf", "secret.pdf.enc", key, associated_data=b"v1")
+decrypt_file("secret.pdf.enc", "secret.pdf", key, associated_data=b"v1")
+```
+
+篡改由 GCM 认证 tag 检测,以 `CryptoException("authentication failed")`
+报告。JSON 动作:`FA_encrypt_file`、`FA_decrypt_file`。
+
+### HTTPActionClient Python SDK
+HTTP 动作服务器的类型化客户端;默认强制 loopback,并自动携带 shared
+secret:
+
+```python
+from automation_file import HTTPActionClient
+
+with HTTPActionClient("http://127.0.0.1:9944", shared_secret="s3cr3t") as client:
+    client.ping()                                       # OPTIONS /actions
+    result = client.execute([["FA_create_dir", {"dir_path": "x"}]])
+```
+
+认证失败会转换为 `HTTPActionClientException(kind="unauthorized")`;
+404 则表示服务器存在但未对外提供 `/actions`。
+
+### Prometheus metrics 导出器
+`ActionExecutor` 为每个动作记录一条计数器与一条直方图样本。在 loopback
+`/metrics` 端点提供:
+
+```python
+from automation_file import start_metrics_server
+
+server = start_metrics_server(host="127.0.0.1", port=9945)
+# curl http://127.0.0.1:9945/metrics
+```
+
+导出 `automation_file_actions_total{action,status}` 以及
+`automation_file_action_duration_seconds{action}`。若要绑定非 loopback
+地址必须显式传入 `allow_non_loopback=True`。
+
 ### DAG 动作执行器
 按依赖顺序执行动作；独立分支通过线程池并行展开。每个节点的形式为
 `{"id": ..., "action": [...], "depends_on": [...]}`：
diff --git a/README.zh-TW.md b/README.zh-TW.md
index 36cf182..ee46f63 100644
--- a/README.zh-TW.md
+++ b/README.zh-TW.md
@@ -25,8 +25,21 @@ TCP / HTTP 伺服器執行的 JSON 驅動動作。內附 PySide6 GUI，每個功
 - **Entry-point 外掛** — 第三方套件透過 `[project.entry-points."automation_file.actions"]` 註冊自訂 `FA_*` 動作；`build_default_registry()` 會自動載入
 - **增量目錄同步** — rsync 風格鏡像，支援 size+mtime 或 checksum 變更偵測，選擇性刪除多餘檔案，支援乾跑（`FA_sync_dir`）
 - **目錄 manifest** — 以 JSON 快照記錄樹下每個檔案的檢查碼，驗證時分開回報 missing / modified / extra（`FA_write_manifest`、`FA_verify_manifest`）
-- **通知 sink** — webhook / Slack / SMTP，fanout 管理器做個別 sink 錯誤隔離與滑動視窗去重；trigger + scheduler 失敗時自動通知（`FA_notify_send`、`FA_notify_list`）
+- **通知 sink** — webhook / Slack / SMTP / Telegram / Discord / Teams / PagerDuty，fanout 管理器做個別 sink 錯誤隔離與滑動視窗去重；trigger + scheduler 失敗時自動通知（`FA_notify_send`、`FA_notify_list`）
 - **設定檔 + 秘密提供者** — 在 `automation_file.toml` 宣告通知 sink / 預設值；`${env:…}` 與 `${file:…}` 參考透過 Env / File / Chained 提供者抽象解析，讓秘密不留在檔案裡
+- **設定熱重載** — `ConfigWatcher` 輪詢 `automation_file.toml`，變更時即時套用 sink / 預設值，無需重啟
+- **Shell / grep / JSON 編輯 / tar / 備份輪替** — `FA_run_shell`（參數列表式 subprocess，含逾時）、`FA_grep`（串流文字搜尋）、`FA_json_get` / `FA_json_set` / `FA_json_delete`（原地 JSON 編輯）、`FA_create_tar` / `FA_extract_tar`、`FA_rotate_backups`
+- **FTP / FTPS 後端** — 純 FTP 或透過 `FTP_TLS.auth()` 的顯式 FTPS；自動註冊為 `FA_ftp_*`
+- **跨後端複製** — `FA_copy_between` 透過 `local://`、`s3://`、`drive://`、`azure://`、`dropbox://`、`sftp://`、`ftp://` URI 在任意兩個後端之間搬運資料
+- **排程器重疊防護** — 正在執行的工作在下次觸發時會被跳過，除非明確傳入 `allow_overlap=True`
+- **伺服器動作 ACL** — `allowed_actions=(...)` 限制 TCP / HTTP 伺服器可派送的指令
+- **變數替換** — 動作參數中可選使用 `${env:VAR}` / `${date:%Y-%m-%d}` / `${uuid}` / `${cwd}`，透過 `execute_action(..., substitute=True)` 展開
+- **條件式執行** — `FA_if_exists` / `FA_if_newer` / `FA_if_size_gt` 僅在路徑守護通過時執行巢狀動作清單
+- **SQLite 稽核日誌** — `AuditLog(db_path)` 為每個動作記錄 actor / status / duration；以 `recent` / `count` / `purge` 查詢
+- **檔案完整性監控** — `IntegrityMonitor` 依 manifest 輪詢整棵樹，偵測到 drift 時觸發 callback + 通知
+- **HTTPActionClient SDK** — HTTP 動作伺服器的型別化 Python 客戶端，具 shared-secret 驗證、loopback 防護與 OPTIONS ping
+- **AES-256-GCM 檔案加密** — `encrypt_file` / `decrypt_file` 搭配 `generate_key()` / `key_from_password()`（PBKDF2-HMAC-SHA256）；JSON 動作 `FA_encrypt_file` / `FA_decrypt_file`
+- **Prometheus metrics 匯出器** — `start_metrics_server()` 提供 `automation_file_actions_total{action,status}` 計數器與 `automation_file_action_duration_seconds{action}` 直方圖
 - PySide6 GUI（`python -m automation_file ui`）每個後端一個分頁，含 JSON 動作執行器，另有 Triggers、Scheduler、即時 Progress 專屬分頁
 - 功能豐富的 CLI，包含一次性子指令與舊式 JSON 批次旗標
 - 專案鷹架（`ProjectBuilder`）協助建立以 executor 為核心的自動化專案
@@ -489,6 +502,115 @@ config.apply_to(notification_manager)
 `FileSecretProvider` 建立自訂提供者鏈，並以
 `AutomationConfig.load(path, provider=…)` 傳入。
 
+### 動作清單變數替換
+以 `substitute=True` 啟用後，`${…}` 參考會在派送時展開：
+
+```python
+from automation_file import execute_action
+
+execute_action(
+    [["FA_create_file", {"file_path": "reports/${date:%Y-%m-%d}/${uuid}.txt"}]],
+    substitute=True,
+)
+```
+
+支援 `${env:VAR}`、`${date:FMT}`（strftime）、`${uuid}`、`${cwd}`。未知名稱
+會拋出 `SubstitutionException`，不會默默變成空字串。
+
+### 條件式執行
+只在路徑守護通過時執行巢狀動作清單：
+
+```json
+[
+  ["FA_if_exists", {"path": "/data/in/job.json",
+                    "then": [["FA_copy_file", {"source": "/data/in/job.json",
+                                               "target": "/data/processed/job.json"}]]}],
+  ["FA_if_newer",  {"source": "/src", "target": "/dst",
+                    "then": [["FA_sync_dir", {"src": "/src", "dst": "/dst"}]]}],
+  ["FA_if_size_gt", {"path": "/logs/app.log", "size": 10485760,
+                     "then": [["FA_run_shell", {"command": ["logrotate", "/logs/app.log"]}]]}]
+]
+```
+
+### SQLite 稽核日誌
+`AuditLog` 以短連線 + 模組層級 lock 為每個動作寫入一筆紀錄：
+
+```python
+from automation_file import AuditLog
+
+audit = AuditLog("audit.sqlite3")
+audit.record(action="FA_copy_file", actor="ops",
+             status="ok", duration_ms=12, detail={"src": "a", "dst": "b"})
+
+for row in audit.recent(limit=50):
+    print(row["timestamp"], row["action"], row["status"])
+```
+
+### 檔案完整性監控
+依 manifest 輪詢整棵樹，偵測到 drift 時觸發 callback + 通知：
+
+```python
+from automation_file import IntegrityMonitor, notification_manager, write_manifest
+
+write_manifest("/srv/site", "/srv/MANIFEST.json")
+
+mon = IntegrityMonitor(
+    root="/srv/site",
+    manifest_path="/srv/MANIFEST.json",
+    interval=60.0,
+    manager=notification_manager,
+    on_drift=lambda summary: print("drift:", summary),
+)
+mon.start()
+```
+
+載入 manifest 時的錯誤也會被視為 drift，讓竄改與設定問題走同一條處理
+路徑。
+
+### AES-256-GCM 檔案加密
+具驗證的加密與自述式封包格式。可由密碼衍生金鑰或直接產生金鑰：
+
+```python
+from automation_file import encrypt_file, decrypt_file, key_from_password
+
+key = key_from_password("correct horse battery staple", salt=b"app-salt-v1")
+encrypt_file("secret.pdf", "secret.pdf.enc", key, associated_data=b"v1")
+decrypt_file("secret.pdf.enc", "secret.pdf", key, associated_data=b"v1")
+```
+
+竄改由 GCM 驗證 tag 偵測，以 `CryptoException("authentication failed")`
+回報。JSON 動作：`FA_encrypt_file`、`FA_decrypt_file`。
+
+### HTTPActionClient Python SDK
+HTTP 動作伺服器的型別化客戶端；預設強制 loopback，並自動附帶 shared
+secret：
+
+```python
+from automation_file import HTTPActionClient
+
+with HTTPActionClient("http://127.0.0.1:9944", shared_secret="s3cr3t") as client:
+    client.ping()                                       # OPTIONS /actions
+    result = client.execute([["FA_create_dir", {"dir_path": "x"}]])
+```
+
+驗證失敗會轉成 `HTTPActionClientException(kind="unauthorized")`;
+404 則表示伺服器存在但未對外提供 `/actions`。
+
+### Prometheus metrics 匯出器
+`ActionExecutor` 為每個動作記錄一筆計數器與一筆直方圖樣本。在 loopback
+`/metrics` 端點提供：
+
+```python
+from automation_file import start_metrics_server
+
+server = start_metrics_server(host="127.0.0.1", port=9945)
+# curl http://127.0.0.1:9945/metrics
+```
+
+匯出 `automation_file_actions_total{action,status}` 以及
+`automation_file_action_duration_seconds{action}`。若要綁定非 loopback
+位址必須明確傳入 `allow_non_loopback=True`。
+
 ### DAG 動作執行器
 依相依關係執行動作；獨立分支會透過執行緒池平行展開。每個節點形式為
 `{"id": ..., "action": [...], "depends_on": [...]}`：
diff --git a/docs/source/api/client.rst b/docs/source/api/client.rst
new file mode 100644
index 0000000..36ab808
--- /dev/null
+++ b/docs/source/api/client.rst
@@ -0,0 +1,5 @@
+Client SDK
+==========
+
+.. automodule:: automation_file.client.http_client
+   :members:
diff --git a/docs/source/api/core.rst b/docs/source/api/core.rst
index e115e43..f91dfdc 100644
--- a/docs/source/api/core.rst
+++ b/docs/source/api/core.rst
@@ -31,6 +31,24 @@ Core
 .. automodule:: automation_file.core.manifest
    :members:
 
+.. automodule:: automation_file.core.fim
+   :members:
+
+.. automodule:: automation_file.core.audit
+   :members:
+
+.. automodule:: automation_file.core.crypto
+   :members:
+
+.. automodule:: automation_file.core.metrics
+   :members:
+
+.. automodule:: automation_file.core.substitution
+   :members:
+
+.. automodule:: automation_file.core.config_watcher
+   :members:
+
 .. automodule:: automation_file.core.plugins
    :members:
 
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index f0014dc..d887919 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -8,6 +8,7 @@ API reference
    local
    remote
    server
+   client
    trigger
    scheduler
    notify
diff --git a/docs/source/api/local.rst b/docs/source/api/local.rst
index dcdb9ed..292c922 100644
--- a/docs/source/api/local.rst
+++ b/docs/source/api/local.rst
@@ -15,3 +15,15 @@ Local operations
 
 .. automodule:: automation_file.local.safe_paths
    :members:
+
+.. automodule:: automation_file.local.shell_ops
+   :members:
+
+.. automodule:: automation_file.local.tar_ops
+   :members:
+
+.. automodule:: automation_file.local.json_edit
+   :members:
+
+.. automodule:: automation_file.local.conditional
+   :members:
diff --git a/docs/source/api/remote.rst b/docs/source/api/remote.rst
index 67e9563..567dd31 100644
--- a/docs/source/api/remote.rst
+++ b/docs/source/api/remote.rst
@@ -115,3 +115,31 @@ Bundled with ``automation_file``; registered automatically by
 
 .. automodule:: automation_file.remote.sftp.list_ops
    :members:
+
+FTP / FTPS
+----------
+
+Bundled with ``automation_file``; registered automatically by
+:func:`automation_file.core.action_registry.build_default_registry`.
+Supports plain FTP and explicit FTPS (via ``FTP_TLS`` + ``auth()``).
+
+.. automodule:: automation_file.remote.ftp.client
+   :members:
+
+.. automodule:: automation_file.remote.ftp.upload_ops
+   :members:
+
+.. automodule:: automation_file.remote.ftp.download_ops
+   :members:
+
+.. automodule:: automation_file.remote.ftp.delete_ops
+   :members:
+
+.. automodule:: automation_file.remote.ftp.list_ops
+   :members:
+
+Cross-backend
+-------------
+
+.. automodule:: automation_file.remote.cross_backend
+   :members:
diff --git a/docs/source/api/server.rst b/docs/source/api/server.rst
index affd5b7..4ec6f57 100644
--- a/docs/source/api/server.rst
+++ b/docs/source/api/server.rst
@@ -6,3 +6,9 @@ Server
 
 .. automodule:: automation_file.server.http_server
    :members:
+
+.. automodule:: automation_file.server.metrics_server
+   :members:
+
+.. automodule:: automation_file.server.action_acl
+   :members:

From f7395a4f89d71ec5c9d2ce12243de06649e00205 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:54:58 +0800
Subject: [PATCH 36/38] Install cryptography and prometheus_client in CI

---
 dev_requirements.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/dev_requirements.txt b/dev_requirements.txt
index 6903992..8399b03 100644
--- a/dev_requirements.txt
+++ b/dev_requirements.txt
@@ -3,5 +3,7 @@ google-api-python-client
 google-auth-httplib2
 google-auth-oauthlib
 APScheduler
+cryptography>=42.0.0
+prometheus_client>=0.20.0
 twine
 build

From 04b2fa7b72d5eec08a7be741fa301284da9f76f6 Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 22:58:09 +0800
Subject: [PATCH 37/38] Install local package from TOML in CI

---
 .github/workflows/ci-dev.yml    | 3 ++-
 .github/workflows/ci-stable.yml | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci-dev.yml b/.github/workflows/ci-dev.yml
index 74ccaaf..dcf43d3 100644
--- a/.github/workflows/ci-dev.yml
+++ b/.github/workflows/ci-dev.yml
@@ -48,7 +48,8 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip wheel
-          pip install -r dev_requirements.txt
+          Copy-Item dev.toml pyproject.toml -Force
+          pip install -e .
           pip install pytest pytest-cov
       - name: Run pytest with coverage
         run: python -m pytest tests/ -v --tb=short --cov=automation_file --cov-report=term-missing --cov-report=xml
diff --git a/.github/workflows/ci-stable.yml b/.github/workflows/ci-stable.yml
index 97f180a..d6911e7 100644
--- a/.github/workflows/ci-stable.yml
+++ b/.github/workflows/ci-stable.yml
@@ -48,7 +48,8 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip wheel
-          pip install -r requirements.txt
+          Copy-Item stable.toml pyproject.toml -Force
+          pip install -e .
           pip install pytest pytest-cov
       - name: Run pytest with coverage
         run: python -m pytest tests/ -v --tb=short --cov=automation_file --cov-report=term-missing --cov-report=xml

From 0dab17ad03fbe7dc61e8c44716b2656e82f536ae Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Tue, 21 Apr 2026 23:03:53 +0800
Subject: [PATCH 38/38] Skip tarfile filter= on Python 3.10 without PEP 706
 backport

---
 automation_file/local/tar_ops.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/automation_file/local/tar_ops.py b/automation_file/local/tar_ops.py
index 17d6fe8..672e74e 100644
--- a/automation_file/local/tar_ops.py
+++ b/automation_file/local/tar_ops.py
@@ -26,6 +26,8 @@
     "xz": "w:xz",
 }
 
+_TAR_FILTER_SUPPORTED = hasattr(tarfile, "data_filter")
+
 
 class TarException(FileAutomationException):
     """Raised when tar creation or extraction fails."""
@@ -77,7 +79,10 @@ def extract_tar(source: str, target_dir: str) -> list[str]:
         with tarfile.open(str(src_path), "r:*") as archive:
             _verify_members(archive, dest)
             for member in archive.getmembers():
-                archive.extract(member, str(dest), filter="data")
+                if _TAR_FILTER_SUPPORTED:
+                    archive.extract(member, str(dest), filter="data")
+                else:
+                    archive.extract(member, str(dest))
                 extracted.append(member.name)
     except PathTraversalException:
         raise