Metadata-Version: 2.4
Name: filepulse
Version: 0.1.0
Summary: 文件监控与归档同步工具 — 轮询检测文件变化并自动同步，支持 zip 归档自动解压处理
Author: songwupei
License: MIT
Project-URL: Homepage, https://codeberg.org/songwupei/filepulse
Project-URL: Repository, https://codeberg.org/songwupei/filepulse
Project-URL: Issues, https://codeberg.org/songwupei/filepulse/issues
Keywords: file-sync,monitor,polling,archive,zip,backup
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Archiving
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: tomli>=2.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: click>=8.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"

# filepulse — 文件监控与归档同步工具

轮询检测源文件变化并自动同步到目标位置，支持 zip 归档自动解压处理。

## 功能特性

- 📁 监控文件变化（时间戳、大小、哈希），自动同步到目标位置
- 📦 监控压缩包（zip），自动解压并分发到多个目标目录
- 🔀 支持扁平化复制（丢弃子目录，文件直达目标）
- 🪝 前后置钩子脚本（sync/archive 处理前后执行自定义逻辑）
- 💾 自动备份功能
- 🔄 可配置的检查间隔
- 📊 运行状态统计
- 🎯 支持简单和复杂映射配置

## 系统要求

- Python ≥ 3.10
- pip install 自动安装依赖 (tomli, tomli-w, click)

## 快速开始

### 1. 安装

```bash
pip install filepulse
```

### 2. 初始化

```bash
filepulse init    # 创建 config.toml, 日志和备份目录
```

### 3. 配置监控文件

编辑 `config.toml`：

```toml
[monitor]
interval = 2.0

[files]
"source/path/file.txt" = "target/path/file.txt"
```

### 4. 启动监控

```bash
# 文件同步
filepulse sync run config.toml              # 前台持续监控
filepulse sync run --daemon config.toml     # 后台运行
filepulse sync once config.toml             # 一次性同步

# 归档处理
filepulse archive run config.toml           # 前台持续扫描
filepulse archive run --daemon config.toml  # 后台运行
filepulse archive once config.toml          # 一次性处理
filepulse archive check config.toml         # 干跑：列出待处理 zip

# 守护进程管理
filepulse daemon status                      # 查看状态
filepulse daemon stop                        # 停止
filepulse daemon logs 50                     # 查看日志
filepulse daemon reload                      # 重载配置
```

## 命令参考

### 文件同步 (`filepulse sync`)

| 命令 | 说明 |
|---|---|
| `sync run <config>` | 前台持续监控 |
| `sync run --daemon <config>` | 后台持续监控 |
| `sync once <config>` | 一次性同步所有变更文件 |
| `sync check <FILE> <config>` | 检查单个文件状态 |
| `sync stats <config>` | 列出配置的文件映射 |

### 归档处理 (`filepulse archive`)

| 命令 | 说明 |
|---|---|
| `archive run <config>` | 前台持续扫描 zip |
| `archive run --daemon <config>` | 后台持续扫描 |
| `archive once <config>` | 一次性处理待处理 zip |
| `archive check <config>` | 干跑：列出待处理 zip |

### 守护进程 (`filepulse daemon`)

| 命令 | 说明 |
|---|---|
| `daemon status` | 查看所有后台进程 |
| `daemon stop` | 停止所有后台进程 |
| `daemon logs [N]` | 查看最近 N 行日志 |
| `daemon reload` | 停止后重新启动 |

### 工具

```bash
filepulse clean               # 清理旧日志和备份
filepulse treasury-run        # 运行司库日报流程
filepulse --version           # 版本信息
```

### Just 别名（可选）

如果安装了 [Just](https://just.systems)，可使用快捷别名：

```bash
just daemon         # → filepulse sync run --daemon config.toml
just foreground     # → filepulse sync run config.toml
just status         # → filepulse daemon status
just stop           # → filepulse daemon stop
just logs           # → filepulse daemon logs 50
```

## 配置说明

### 文件同步配置

**简单格式**：
```toml
[files]
"源文件路径" = "目标文件路径"
```

**详细格式（带钩子）**：
```toml
[files.my_entry]
source = "/path/to/source.xlsx"
target = "/path/to/target.xlsx"
on_before_sync = ""   # 前置钩子脚本
on_after_sync = ""    # 后置钩子脚本
```

**监控选项** (`[monitor]`)：
- `interval`: 检查间隔（秒，默认 2.0）
- `check_size`: 检查文件大小变化（默认 true）
- `check_mtime`: 检查修改时间变化（默认 true）
- `check_hash`: 检查文件哈希变化（默认 false）
- `create_backup`: 同步前创建备份（默认 true）
- `backup_dir`: 备份文件目录（默认 "backup"）

### 归档处理配置

```toml
[archive_monitor]
interval = 10.0                    # 检查间隔（秒）
extract_temp = "/tmp/sync_extract" # 解压临时目录
base_dir = "/path/to/base"         # 源文件扫描根目录

[[archives]]
name = "任务名"
source_pattern = "inbox/通道-*/data-*.zip"  # glob 模式（相对于 base_dir）
target_dirs = ["/path/to/output1", "/path/to/output2"]  # 多目标（推荐）
flatten_targets = ["/path/to/output2"]  # 扁平化目标（丢弃子目录）
rename_to = ""                     # 解压后重命名顶层目录
archive_dir = "/path/to/processed" # 已处理 zip 归档位置
on_before_process = ""             # 前置钩子脚本
on_after_process = ""              # 后置钩子脚本
```

### 钩子环境变量

| 变量 | 文件同步 | 归档处理 |
|---|---|---|
| `MONITOR_TYPE` | `file_sync` | `archive` |
| `MONITOR_EVENT` | `before_sync` / `after_sync` | `before_process` / `after_process` |
| `MONITOR_SOURCE` | 源文件路径 | zip 文件路径 |
| `MONITOR_TARGET` | 目标文件路径 | 目标目录 |
| `MONITOR_TASK` | file_id | 任务名 |
| `MONITOR_EXTRACTED` | — | 目标目录（仅后置钩子） |

### 状态文件与路径

filepulse 遵循 XDG 规范存储运行时数据：

- 状态文件: `~/.local/share/filepulse/` (或 `$XDG_DATA_HOME/filepulse/`)
- 日志文件: `~/.cache/filepulse/` (或 `$XDG_CACHE_HOME/filepulse/`)
- PID 文件: `~/.local/share/filepulse/`

可通过环境变量覆盖：`FILEPULSE_DATA_DIR`, `FILEPULSE_CACHE_DIR`

## 迁移指南

从旧 `monitor.py` 迁移：

| 旧 | 新 |
|---|---|
| `python monitor.py config.toml --foreground` | `filepulse sync run config.toml` |
| `python monitor.py config.toml --daemon` | `filepulse sync run --daemon config.toml` |
| `python monitor.py config.toml --sync-all` | `filepulse sync once config.toml` |
| `python monitor.py config.toml --check <F>` | `filepulse sync check <F> config.toml` |
| `python monitor.py config.toml --stats` | `filepulse sync stats config.toml` |
| `python monitor.py config.toml --archive-foreground` | `filepulse archive run config.toml` |
| `python monitor.py config.toml --archive-daemon` | `filepulse archive run --daemon config.toml` |
| `python monitor.py config.toml --archive-sync` | `filepulse archive once config.toml` |
| `python monitor.py config.toml --archive-check` | `filepulse archive check config.toml` |

配置文件 100% 向后兼容。

## 故障排除

- **导入错误** → `pip install filepulse` 会自动安装依赖
- **文件未同步** → `filepulse daemon logs 50` 查看日志
- **归档 zip 未处理** → `filepulse archive check config.toml` 干跑
- **前台调试** → `filepulse archive run config.toml` 前台运行查看实时输出
