clutterxp 1.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- clutterxp/__init__.py +4 -0
- clutterxp/cli/__init__.py +7 -0
- clutterxp/cli/app.py +251 -0
- clutterxp/cli/cmd_config.py +250 -0
- clutterxp/cli/cmd_doctor.py +449 -0
- clutterxp/cli/cmd_duplicates.py +253 -0
- clutterxp/cli/cmd_gui.py +22 -0
- clutterxp/cli/cmd_history.py +233 -0
- clutterxp/cli/cmd_init.py +76 -0
- clutterxp/cli/cmd_organize.py +226 -0
- clutterxp/cli/cmd_rules.py +540 -0
- clutterxp/cli/cmd_scan.py +109 -0
- clutterxp/cli/cmd_service.py +130 -0
- clutterxp/cli/cmd_undo.py +180 -0
- clutterxp/cli/cmd_watch.py +147 -0
- clutterxp/cli/errors.py +166 -0
- clutterxp/cli/render.py +390 -0
- clutterxp/config/__init__.py +40 -0
- clutterxp/config/jsonschema.py +12 -0
- clutterxp/config/loader.py +212 -0
- clutterxp/config/placeholders.py +79 -0
- clutterxp/config/runtime.py +30 -0
- clutterxp/config/schema.py +166 -0
- clutterxp/config/validate.py +226 -0
- clutterxp/config/writer.py +248 -0
- clutterxp/config.example.yaml +76 -0
- clutterxp/duplicates/__init__.py +22 -0
- clutterxp/duplicates/detector.py +438 -0
- clutterxp/duplicates/hashcache.py +149 -0
- clutterxp/duplicates/namenorm.py +45 -0
- clutterxp/duplicates/quarantine.py +196 -0
- clutterxp/duplicates/report.py +110 -0
- clutterxp/gui/__init__.py +1 -0
- clutterxp/gui/api.py +494 -0
- clutterxp/gui/app.py +205 -0
- clutterxp/gui/models_qt.py +544 -0
- clutterxp/gui/views/__init__.py +21 -0
- clutterxp/gui/views/dashboard.py +253 -0
- clutterxp/gui/views/duplicates.py +404 -0
- clutterxp/gui/views/folders.py +354 -0
- clutterxp/gui/views/history.py +281 -0
- clutterxp/gui/views/preview.py +277 -0
- clutterxp/gui/views/rules.py +527 -0
- clutterxp/gui/views/settings.py +172 -0
- clutterxp/gui/workers.py +147 -0
- clutterxp/history/__init__.py +23 -0
- clutterxp/history/db.py +174 -0
- clutterxp/history/pathcodec.py +42 -0
- clutterxp/history/recovery.py +318 -0
- clutterxp/history/schema.sql +43 -0
- clutterxp/history/service.py +493 -0
- clutterxp/history/undo.py +373 -0
- clutterxp/interfaces.py +164 -0
- clutterxp/locking.py +113 -0
- clutterxp/logging_setup.py +73 -0
- clutterxp/models.py +266 -0
- clutterxp/mover/__init__.py +26 -0
- clutterxp/mover/collision.py +46 -0
- clutterxp/mover/fsops.py +191 -0
- clutterxp/mover/safe_move.py +741 -0
- clutterxp/organizer.py +388 -0
- clutterxp/packaging/clutterxp.service +15 -0
- clutterxp/paths.py +112 -0
- clutterxp/planner.py +339 -0
- clutterxp/py.typed +0 -0
- clutterxp/rules/__init__.py +16 -0
- clutterxp/rules/engine.py +374 -0
- clutterxp/rules/matcher.py +222 -0
- clutterxp/rules/template.py +171 -0
- clutterxp/rules/tokenizer.py +118 -0
- clutterxp/safety.py +111 -0
- clutterxp/scanner.py +196 -0
- clutterxp/service_install.py +208 -0
- clutterxp/units.py +59 -0
- clutterxp/watch/__init__.py +37 -0
- clutterxp/watch/debounce.py +84 -0
- clutterxp/watch/events.py +259 -0
- clutterxp/watch/ignore.py +77 -0
- clutterxp/watch/service.py +662 -0
- clutterxp/watch/settle.py +170 -0
- clutterxp-1.1.0.dist-info/METADATA +149 -0
- clutterxp-1.1.0.dist-info/RECORD +84 -0
- clutterxp-1.1.0.dist-info/WHEEL +4 -0
- clutterxp-1.1.0.dist-info/entry_points.txt +6 -0
clutterxp/gui/workers.py
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
"""Background worker threads, QRunnable tasks, signals, and cancellation tokens.
|
|
2
|
+
|
|
3
|
+
Ensures the UI thread never performs blocking file I/O, DB access, or hashing.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import logging
|
|
9
|
+
import threading
|
|
10
|
+
from collections.abc import Callable
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
from PySide6.QtCore import QObject, QRunnable, QThreadPool, Signal, Slot
|
|
14
|
+
|
|
15
|
+
logger = logging.getLogger(__name__)
|
|
16
|
+
|
|
17
|
+
# Keep strong references to running workers to prevent premature GC by Python
|
|
18
|
+
_ACTIVE_WORKERS: set[TaskWorker] = set()
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class WorkerSignals(QObject):
|
|
22
|
+
"""Signals emitted by background workers."""
|
|
23
|
+
|
|
24
|
+
started = Signal()
|
|
25
|
+
finished = Signal()
|
|
26
|
+
error = Signal(Exception)
|
|
27
|
+
result = Signal(object)
|
|
28
|
+
progress = Signal(int, int)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class CancellationToken:
|
|
32
|
+
"""Thread-safe cancellation token wrapping a threading.Event."""
|
|
33
|
+
|
|
34
|
+
def __init__(self) -> None:
|
|
35
|
+
self._event = threading.Event()
|
|
36
|
+
|
|
37
|
+
def cancel(self) -> None:
|
|
38
|
+
"""Signal cancellation."""
|
|
39
|
+
self._event.set()
|
|
40
|
+
|
|
41
|
+
def reset(self) -> None:
|
|
42
|
+
"""Reset cancellation token."""
|
|
43
|
+
self._event.clear()
|
|
44
|
+
|
|
45
|
+
@property
|
|
46
|
+
def is_cancelled(self) -> bool:
|
|
47
|
+
return self._event.is_set()
|
|
48
|
+
|
|
49
|
+
@property
|
|
50
|
+
def event(self) -> threading.Event:
|
|
51
|
+
return self._event
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class TaskWorker(QRunnable):
|
|
55
|
+
"""QRunnable wrapper to execute any blocking function on QThreadPool."""
|
|
56
|
+
|
|
57
|
+
def __init__(
|
|
58
|
+
self,
|
|
59
|
+
fn: Callable[..., Any],
|
|
60
|
+
*args: Any,
|
|
61
|
+
cancel_event: threading.Event | CancellationToken | None = None,
|
|
62
|
+
with_progress: bool = False,
|
|
63
|
+
**kwargs: Any,
|
|
64
|
+
) -> None:
|
|
65
|
+
super().__init__()
|
|
66
|
+
self.fn = fn
|
|
67
|
+
self.args = args
|
|
68
|
+
self.kwargs = kwargs
|
|
69
|
+
if isinstance(cancel_event, CancellationToken):
|
|
70
|
+
self.cancel_event: threading.Event | None = cancel_event.event
|
|
71
|
+
else:
|
|
72
|
+
self.cancel_event = cancel_event
|
|
73
|
+
self.with_progress = with_progress
|
|
74
|
+
self.signals = WorkerSignals()
|
|
75
|
+
self.setAutoDelete(True)
|
|
76
|
+
|
|
77
|
+
def _progress_cb(self, current: int, total: int) -> None:
|
|
78
|
+
self.signals.progress.emit(current, total)
|
|
79
|
+
|
|
80
|
+
@Slot()
|
|
81
|
+
def run(self) -> None:
|
|
82
|
+
"""Execute the task and emit result or error."""
|
|
83
|
+
self.signals.started.emit()
|
|
84
|
+
try:
|
|
85
|
+
call_kwargs = dict(self.kwargs)
|
|
86
|
+
if self.cancel_event is not None and "cancel" not in call_kwargs:
|
|
87
|
+
call_kwargs["cancel"] = self.cancel_event
|
|
88
|
+
if self.with_progress and "progress" not in call_kwargs:
|
|
89
|
+
call_kwargs["progress"] = self._progress_cb
|
|
90
|
+
|
|
91
|
+
res = self.fn(*self.args, **call_kwargs)
|
|
92
|
+
self.signals.result.emit(res)
|
|
93
|
+
except Exception as exc:
|
|
94
|
+
logger.exception("Task worker encountered exception: %s", exc)
|
|
95
|
+
self.signals.error.emit(exc)
|
|
96
|
+
finally:
|
|
97
|
+
self.signals.finished.emit()
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def run_in_worker(
|
|
101
|
+
fn: Callable[..., Any],
|
|
102
|
+
*args: Any,
|
|
103
|
+
cancel_token: CancellationToken | threading.Event | None = None,
|
|
104
|
+
with_progress: bool = False,
|
|
105
|
+
on_result: Callable[[Any], None] | None = None,
|
|
106
|
+
on_error: Callable[[Exception], None] | None = None,
|
|
107
|
+
on_progress: Callable[[int, int], None] | None = None,
|
|
108
|
+
on_finished: Callable[[], None] | None = None,
|
|
109
|
+
pool: QThreadPool | None = None,
|
|
110
|
+
**kwargs: Any,
|
|
111
|
+
) -> TaskWorker:
|
|
112
|
+
"""Helper to instantiate and launch a TaskWorker on the thread pool."""
|
|
113
|
+
worker = TaskWorker(
|
|
114
|
+
fn,
|
|
115
|
+
*args,
|
|
116
|
+
cancel_event=cancel_token,
|
|
117
|
+
with_progress=with_progress,
|
|
118
|
+
**kwargs,
|
|
119
|
+
)
|
|
120
|
+
|
|
121
|
+
_ACTIVE_WORKERS.add(worker)
|
|
122
|
+
|
|
123
|
+
def _cleanup() -> None:
|
|
124
|
+
_ACTIVE_WORKERS.discard(worker)
|
|
125
|
+
if on_finished is not None:
|
|
126
|
+
on_finished()
|
|
127
|
+
|
|
128
|
+
if on_result is not None:
|
|
129
|
+
worker.signals.result.connect(on_result)
|
|
130
|
+
if on_error is not None:
|
|
131
|
+
worker.signals.error.connect(on_error)
|
|
132
|
+
if on_progress is not None:
|
|
133
|
+
worker.signals.progress.connect(on_progress)
|
|
134
|
+
|
|
135
|
+
worker.signals.finished.connect(_cleanup)
|
|
136
|
+
|
|
137
|
+
thread_pool = pool if pool is not None else QThreadPool.globalInstance()
|
|
138
|
+
thread_pool.start(worker)
|
|
139
|
+
return worker
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
__all__ = [
|
|
143
|
+
"CancellationToken",
|
|
144
|
+
"TaskWorker",
|
|
145
|
+
"WorkerSignals",
|
|
146
|
+
"run_in_worker",
|
|
147
|
+
]
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""History: operations journal, SQLite storage, undo, and crash recovery."""
|
|
2
|
+
|
|
3
|
+
from clutterxp.history.db import (
|
|
4
|
+
CURRENT_SCHEMA_VERSION,
|
|
5
|
+
connect,
|
|
6
|
+
handle_corrupt_db,
|
|
7
|
+
integrity_check,
|
|
8
|
+
run_migrations,
|
|
9
|
+
)
|
|
10
|
+
from clutterxp.history.pathcodec import decode, encode
|
|
11
|
+
from clutterxp.history.service import HistoryService, op_to_dict
|
|
12
|
+
|
|
13
|
+
__all__ = [
|
|
14
|
+
"CURRENT_SCHEMA_VERSION",
|
|
15
|
+
"HistoryService",
|
|
16
|
+
"connect",
|
|
17
|
+
"decode",
|
|
18
|
+
"encode",
|
|
19
|
+
"handle_corrupt_db",
|
|
20
|
+
"integrity_check",
|
|
21
|
+
"op_to_dict",
|
|
22
|
+
"run_migrations",
|
|
23
|
+
]
|
clutterxp/history/db.py
ADDED
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
"""SQLite connection, schema migration, permissions, and corruption recovery."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import contextlib
|
|
6
|
+
import logging
|
|
7
|
+
import os
|
|
8
|
+
import sqlite3
|
|
9
|
+
import time
|
|
10
|
+
import warnings
|
|
11
|
+
from collections.abc import Callable
|
|
12
|
+
from datetime import datetime, timezone
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
|
|
15
|
+
logger = logging.getLogger("clutterxp.history.db")
|
|
16
|
+
|
|
17
|
+
SCHEMA_PATH = Path(__file__).resolve().parent / "schema.sql"
|
|
18
|
+
CURRENT_SCHEMA_VERSION = 1
|
|
19
|
+
|
|
20
|
+
MigrationFn = Callable[[sqlite3.Connection], None]
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def _migrate_v1(conn: sqlite3.Connection) -> None:
|
|
24
|
+
"""Version 1 migration: create initial tables and indexes from schema.sql."""
|
|
25
|
+
schema_sql = SCHEMA_PATH.read_text(encoding="utf-8")
|
|
26
|
+
for stmt in schema_sql.split(";"):
|
|
27
|
+
stmt = stmt.strip()
|
|
28
|
+
if stmt:
|
|
29
|
+
conn.execute(stmt)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
MIGRATIONS: dict[int, MigrationFn] = {
|
|
33
|
+
1: _migrate_v1,
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def integrity_check(conn: sqlite3.Connection) -> bool:
|
|
38
|
+
"""Run PRAGMA integrity_check. Returns True if ok."""
|
|
39
|
+
try:
|
|
40
|
+
cur = conn.execute("PRAGMA integrity_check;")
|
|
41
|
+
rows = [row[0] for row in cur.fetchall()]
|
|
42
|
+
return len(rows) == 1 and str(rows[0]).strip().lower() == "ok"
|
|
43
|
+
except sqlite3.DatabaseError:
|
|
44
|
+
return False
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def run_migrations(
|
|
48
|
+
conn: sqlite3.Connection,
|
|
49
|
+
custom_migrations: dict[int, MigrationFn] | None = None,
|
|
50
|
+
) -> None:
|
|
51
|
+
"""Apply any pending migrations in order.
|
|
52
|
+
|
|
53
|
+
Each migration runs in its own transaction.
|
|
54
|
+
Current schema is version 1.
|
|
55
|
+
"""
|
|
56
|
+
migrations = dict(MIGRATIONS)
|
|
57
|
+
if custom_migrations:
|
|
58
|
+
migrations.update(custom_migrations)
|
|
59
|
+
|
|
60
|
+
for version in sorted(migrations.keys()):
|
|
61
|
+
conn.execute("BEGIN IMMEDIATE;")
|
|
62
|
+
try:
|
|
63
|
+
cur = conn.execute("PRAGMA user_version;")
|
|
64
|
+
row = cur.fetchone()
|
|
65
|
+
current_version = row[0] if row else 0
|
|
66
|
+
if version > current_version:
|
|
67
|
+
migrations[version](conn)
|
|
68
|
+
conn.execute(f"PRAGMA user_version = {version};")
|
|
69
|
+
conn.execute("COMMIT;")
|
|
70
|
+
except Exception:
|
|
71
|
+
conn.execute("ROLLBACK;")
|
|
72
|
+
raise
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def handle_corrupt_db(db_path: Path) -> sqlite3.Connection:
|
|
76
|
+
"""Rename to history.db.corrupt-<timestamp>, create fresh DB, warn."""
|
|
77
|
+
ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
|
|
78
|
+
corrupt_path = db_path.parent / f"{db_path.name}.corrupt-{ts}"
|
|
79
|
+
counter = 1
|
|
80
|
+
while corrupt_path.exists():
|
|
81
|
+
corrupt_path = db_path.parent / f"{db_path.name}.corrupt-{ts}-{counter}"
|
|
82
|
+
counter += 1
|
|
83
|
+
|
|
84
|
+
msg = f"Database {db_path} is corrupt. Renaming to {corrupt_path} and creating fresh database."
|
|
85
|
+
warnings.warn(msg, RuntimeWarning, stacklevel=2)
|
|
86
|
+
logger.warning(msg)
|
|
87
|
+
|
|
88
|
+
if db_path.exists():
|
|
89
|
+
db_path.rename(corrupt_path)
|
|
90
|
+
|
|
91
|
+
for ext in ("-wal", "-shm"):
|
|
92
|
+
aux = Path(f"{db_path}{ext}")
|
|
93
|
+
if aux.exists():
|
|
94
|
+
aux.rename(Path(f"{corrupt_path}{ext}"))
|
|
95
|
+
|
|
96
|
+
return connect(db_path)
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def is_corrupt_error(err: Exception) -> bool:
|
|
100
|
+
"""Return True if an exception indicates SQLite database corruption."""
|
|
101
|
+
msg = str(err).lower()
|
|
102
|
+
return any(
|
|
103
|
+
s in msg
|
|
104
|
+
for s in (
|
|
105
|
+
"file is not a database",
|
|
106
|
+
"file is encrypted",
|
|
107
|
+
"database disk image is malformed",
|
|
108
|
+
"malformed database schema",
|
|
109
|
+
"corrupt",
|
|
110
|
+
)
|
|
111
|
+
)
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def connect(db_path: Path) -> sqlite3.Connection:
|
|
115
|
+
"""Open (or create) the DB with correct pragmas and permissions.
|
|
116
|
+
|
|
117
|
+
File created 0600. Schema applied if new.
|
|
118
|
+
Returns connection with check_same_thread=True.
|
|
119
|
+
Runs migrations if user_version < current.
|
|
120
|
+
"""
|
|
121
|
+
is_memory = str(db_path) == ":memory:"
|
|
122
|
+
resolved_path = Path(db_path)
|
|
123
|
+
|
|
124
|
+
if not is_memory:
|
|
125
|
+
resolved_path = resolved_path.resolve()
|
|
126
|
+
resolved_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
|
|
127
|
+
with contextlib.suppress(OSError):
|
|
128
|
+
resolved_path.parent.chmod(0o700)
|
|
129
|
+
if not resolved_path.exists():
|
|
130
|
+
with contextlib.suppress(FileExistsError):
|
|
131
|
+
fd = os.open(resolved_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
|
|
132
|
+
os.close(fd)
|
|
133
|
+
with contextlib.suppress(OSError):
|
|
134
|
+
resolved_path.chmod(0o600)
|
|
135
|
+
|
|
136
|
+
conn: sqlite3.Connection | None = None
|
|
137
|
+
try:
|
|
138
|
+
conn = sqlite3.connect(
|
|
139
|
+
str(resolved_path) if not is_memory else ":memory:",
|
|
140
|
+
timeout=10.0,
|
|
141
|
+
check_same_thread=True,
|
|
142
|
+
isolation_level=None,
|
|
143
|
+
)
|
|
144
|
+
conn.row_factory = sqlite3.Row
|
|
145
|
+
|
|
146
|
+
for attempt in range(20):
|
|
147
|
+
try:
|
|
148
|
+
conn.execute("PRAGMA journal_mode = WAL;")
|
|
149
|
+
break
|
|
150
|
+
except sqlite3.OperationalError as e:
|
|
151
|
+
is_lock = "locked" in str(e).lower() or "busy" in str(e).lower()
|
|
152
|
+
if is_lock and attempt < 19:
|
|
153
|
+
time.sleep(0.02 * (attempt + 1))
|
|
154
|
+
else:
|
|
155
|
+
raise
|
|
156
|
+
|
|
157
|
+
conn.execute("PRAGMA synchronous = FULL;")
|
|
158
|
+
conn.execute("PRAGMA foreign_keys = ON;")
|
|
159
|
+
conn.execute("PRAGMA busy_timeout = 5000;")
|
|
160
|
+
|
|
161
|
+
run_migrations(conn)
|
|
162
|
+
|
|
163
|
+
if not is_memory:
|
|
164
|
+
with contextlib.suppress(OSError):
|
|
165
|
+
resolved_path.chmod(0o600)
|
|
166
|
+
|
|
167
|
+
return conn
|
|
168
|
+
except Exception as err:
|
|
169
|
+
if conn is not None:
|
|
170
|
+
with contextlib.suppress(Exception):
|
|
171
|
+
conn.close()
|
|
172
|
+
if not is_memory and is_corrupt_error(err):
|
|
173
|
+
return handle_corrupt_db(resolved_path)
|
|
174
|
+
raise
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"""Path encoding and decoding for SQLite storage of arbitrary POSIX paths.
|
|
2
|
+
|
|
3
|
+
Linux file names are bytes. Python gives str with surrogate escapes for non-UTF-8
|
|
4
|
+
names, which SQLite cannot store. This codec provides transparent round-tripping
|
|
5
|
+
by base64-encoding non-UTF-8 byte sequences with a sentinel prefix.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import base64
|
|
11
|
+
import os
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
|
|
14
|
+
MARKER = "\x01b64:"
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def encode(path: Path) -> str:
|
|
18
|
+
"""Encode path to str safe for SQLite storage.
|
|
19
|
+
|
|
20
|
+
If fsencode(path) is valid UTF-8, return str(path).
|
|
21
|
+
Otherwise return MARKER + base64(raw bytes).
|
|
22
|
+
"""
|
|
23
|
+
raw_bytes = os.fsencode(path)
|
|
24
|
+
try:
|
|
25
|
+
raw_bytes.decode("utf-8")
|
|
26
|
+
return os.fspath(path)
|
|
27
|
+
except UnicodeDecodeError:
|
|
28
|
+
encoded_b64 = base64.b64encode(raw_bytes).decode("ascii")
|
|
29
|
+
return f"{MARKER}{encoded_b64}"
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def decode(text: str) -> Path:
|
|
33
|
+
"""Reverse of encode.
|
|
34
|
+
|
|
35
|
+
If text starts with MARKER, base64-decode and fsdecode.
|
|
36
|
+
Otherwise Path(text).
|
|
37
|
+
"""
|
|
38
|
+
if text.startswith(MARKER):
|
|
39
|
+
raw_b64 = text[len(MARKER) :]
|
|
40
|
+
raw_bytes = base64.b64decode(raw_b64.encode("ascii"))
|
|
41
|
+
return Path(os.fsdecode(raw_bytes))
|
|
42
|
+
return Path(text)
|
|
@@ -0,0 +1,318 @@
|
|
|
1
|
+
"""Crash recovery service: reconciles pending journal rows on startup or doctor."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import logging
|
|
6
|
+
import os
|
|
7
|
+
import stat
|
|
8
|
+
from collections.abc import Sequence
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from datetime import datetime, timezone
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from clutterxp.interfaces import History
|
|
14
|
+
from clutterxp.models import MoveResult, MoveStrategy, OperationRecord
|
|
15
|
+
|
|
16
|
+
logger = logging.getLogger(__name__)
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
@dataclass(frozen=True)
|
|
20
|
+
class RecoveryAction:
|
|
21
|
+
"""Outcome of reconciling a single pending operation."""
|
|
22
|
+
|
|
23
|
+
op_id: int
|
|
24
|
+
src_path: Path
|
|
25
|
+
dst_path: Path | None
|
|
26
|
+
action_taken: str # "marked_failed" | "marked_done" | "conflict_warning"
|
|
27
|
+
message: str
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _path_to_str(p: Path | None) -> str:
|
|
31
|
+
"""Safely format a Path to string, escaping non-UTF-8 surrogates for SQLite."""
|
|
32
|
+
if p is None:
|
|
33
|
+
return ""
|
|
34
|
+
return os.fsencode(p).decode("utf-8", errors="backslashreplace")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def _parse_iso(s: str) -> datetime:
|
|
38
|
+
"""Parse ISO-8601 string into datetime in UTC."""
|
|
39
|
+
normalized = s.replace("Z", "+00:00")
|
|
40
|
+
try:
|
|
41
|
+
dt = datetime.fromisoformat(normalized)
|
|
42
|
+
if dt.tzinfo is None:
|
|
43
|
+
return dt.replace(tzinfo=timezone.utc)
|
|
44
|
+
return dt.astimezone(timezone.utc)
|
|
45
|
+
except ValueError:
|
|
46
|
+
return datetime.now(timezone.utc)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _find_matching_dest(
|
|
50
|
+
op: OperationRecord,
|
|
51
|
+
planned_dirs: Sequence[Path],
|
|
52
|
+
) -> Path | None:
|
|
53
|
+
"""Search candidate directories for a single file matching op's name, size, and mtime_ns."""
|
|
54
|
+
matches: list[Path] = []
|
|
55
|
+
for d in planned_dirs:
|
|
56
|
+
if not d.is_dir():
|
|
57
|
+
continue
|
|
58
|
+
try:
|
|
59
|
+
if d.resolve() == op.src_path.parent.resolve():
|
|
60
|
+
continue
|
|
61
|
+
except OSError:
|
|
62
|
+
pass
|
|
63
|
+
candidate = d / op.src_path.name
|
|
64
|
+
try:
|
|
65
|
+
if candidate.resolve() == op.src_path.resolve():
|
|
66
|
+
continue
|
|
67
|
+
st = candidate.lstat()
|
|
68
|
+
if not stat.S_ISREG(st.st_mode):
|
|
69
|
+
continue
|
|
70
|
+
if op.size is not None and st.st_size != op.size:
|
|
71
|
+
continue
|
|
72
|
+
if op.mtime_ns is not None and st.st_mtime_ns != op.mtime_ns:
|
|
73
|
+
continue
|
|
74
|
+
matches.append(candidate)
|
|
75
|
+
except (FileNotFoundError, OSError):
|
|
76
|
+
continue
|
|
77
|
+
if len(matches) == 1:
|
|
78
|
+
return matches[0]
|
|
79
|
+
return None
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _reconcile_single_op(
|
|
83
|
+
history: History,
|
|
84
|
+
op: OperationRecord,
|
|
85
|
+
planned_dirs: Sequence[Path] | None = None,
|
|
86
|
+
) -> RecoveryAction:
|
|
87
|
+
"""Examine filesystem state for a single pending op and reconcile its status."""
|
|
88
|
+
dst_path = op.dst_path
|
|
89
|
+
|
|
90
|
+
# Case 5: dst_path is None (unknown destination)
|
|
91
|
+
if dst_path is None:
|
|
92
|
+
search_dirs: list[Path] = list(planned_dirs) if planned_dirs else []
|
|
93
|
+
matched = _find_matching_dest(op, search_dirs) if search_dirs else None
|
|
94
|
+
if matched is not None:
|
|
95
|
+
dst_path = matched
|
|
96
|
+
else:
|
|
97
|
+
# Destination not found in planned directories
|
|
98
|
+
src_exists = os.path.lexists(op.src_path)
|
|
99
|
+
msg = "rolled back: not moved" if src_exists else "source and destination missing"
|
|
100
|
+
history.finish_op(
|
|
101
|
+
op.id,
|
|
102
|
+
MoveResult(
|
|
103
|
+
ok=False,
|
|
104
|
+
src=op.src_path,
|
|
105
|
+
dst=None,
|
|
106
|
+
strategy=None,
|
|
107
|
+
message=msg,
|
|
108
|
+
),
|
|
109
|
+
)
|
|
110
|
+
history.record_event(
|
|
111
|
+
kind="recovery",
|
|
112
|
+
message=msg,
|
|
113
|
+
level="info",
|
|
114
|
+
batch_id=op.batch_id,
|
|
115
|
+
op_id=op.id,
|
|
116
|
+
path=op.src_path,
|
|
117
|
+
)
|
|
118
|
+
return RecoveryAction(
|
|
119
|
+
op_id=op.id,
|
|
120
|
+
src_path=op.src_path,
|
|
121
|
+
dst_path=None,
|
|
122
|
+
action_taken="marked_failed",
|
|
123
|
+
message=msg,
|
|
124
|
+
)
|
|
125
|
+
|
|
126
|
+
src_exists = os.path.lexists(op.src_path)
|
|
127
|
+
dst_exists = os.path.lexists(dst_path) if dst_path is not None else False
|
|
128
|
+
src_display = _path_to_str(op.src_path)
|
|
129
|
+
dst_display = _path_to_str(dst_path)
|
|
130
|
+
|
|
131
|
+
# Case 1: src exists, dst missing -> crashed before move
|
|
132
|
+
if src_exists and not dst_exists:
|
|
133
|
+
msg = "rolled back: not moved"
|
|
134
|
+
history.finish_op(
|
|
135
|
+
op.id,
|
|
136
|
+
MoveResult(
|
|
137
|
+
ok=False,
|
|
138
|
+
src=op.src_path,
|
|
139
|
+
dst=dst_path,
|
|
140
|
+
strategy=None,
|
|
141
|
+
message=msg,
|
|
142
|
+
),
|
|
143
|
+
)
|
|
144
|
+
history.record_event(
|
|
145
|
+
kind="recovery",
|
|
146
|
+
message=msg,
|
|
147
|
+
level="info",
|
|
148
|
+
batch_id=op.batch_id,
|
|
149
|
+
op_id=op.id,
|
|
150
|
+
path=op.src_path,
|
|
151
|
+
)
|
|
152
|
+
return RecoveryAction(
|
|
153
|
+
op_id=op.id,
|
|
154
|
+
src_path=op.src_path,
|
|
155
|
+
dst_path=dst_path,
|
|
156
|
+
action_taken="marked_failed",
|
|
157
|
+
message=msg,
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
# Case 2: src missing, dst exists -> crashed after move
|
|
161
|
+
if not src_exists and dst_exists:
|
|
162
|
+
size_matches = False
|
|
163
|
+
if dst_path is not None:
|
|
164
|
+
try:
|
|
165
|
+
dst_st = dst_path.lstat()
|
|
166
|
+
size_matches = op.size is None or dst_st.st_size == op.size
|
|
167
|
+
except OSError:
|
|
168
|
+
size_matches = False
|
|
169
|
+
|
|
170
|
+
if size_matches:
|
|
171
|
+
msg = f"completed: destination verified at {dst_display}"
|
|
172
|
+
strat = op.strategy or MoveStrategy.RENAME_NOREPLACE
|
|
173
|
+
history.finish_op(
|
|
174
|
+
op.id,
|
|
175
|
+
MoveResult(
|
|
176
|
+
ok=True,
|
|
177
|
+
src=op.src_path,
|
|
178
|
+
dst=dst_path,
|
|
179
|
+
strategy=strat,
|
|
180
|
+
message="",
|
|
181
|
+
),
|
|
182
|
+
)
|
|
183
|
+
history.record_event(
|
|
184
|
+
kind="recovery",
|
|
185
|
+
message=f"Completed move: {src_display} -> {dst_display}",
|
|
186
|
+
level="info",
|
|
187
|
+
batch_id=op.batch_id,
|
|
188
|
+
op_id=op.id,
|
|
189
|
+
path=dst_path,
|
|
190
|
+
)
|
|
191
|
+
return RecoveryAction(
|
|
192
|
+
op_id=op.id,
|
|
193
|
+
src_path=op.src_path,
|
|
194
|
+
dst_path=dst_path,
|
|
195
|
+
action_taken="marked_done",
|
|
196
|
+
message=msg,
|
|
197
|
+
)
|
|
198
|
+
|
|
199
|
+
# Destination size does not match recorded size
|
|
200
|
+
msg = f"destination size mismatch at {dst_display}"
|
|
201
|
+
history.finish_op(
|
|
202
|
+
op.id,
|
|
203
|
+
MoveResult(
|
|
204
|
+
ok=False,
|
|
205
|
+
src=op.src_path,
|
|
206
|
+
dst=dst_path,
|
|
207
|
+
strategy=None,
|
|
208
|
+
message=msg,
|
|
209
|
+
),
|
|
210
|
+
)
|
|
211
|
+
history.record_event(
|
|
212
|
+
kind="recovery",
|
|
213
|
+
message=msg,
|
|
214
|
+
level="error",
|
|
215
|
+
batch_id=op.batch_id,
|
|
216
|
+
op_id=op.id,
|
|
217
|
+
path=dst_path,
|
|
218
|
+
)
|
|
219
|
+
return RecoveryAction(
|
|
220
|
+
op_id=op.id,
|
|
221
|
+
src_path=op.src_path,
|
|
222
|
+
dst_path=dst_path,
|
|
223
|
+
action_taken="marked_failed",
|
|
224
|
+
message=msg,
|
|
225
|
+
)
|
|
226
|
+
|
|
227
|
+
# Case 3: src exists, dst exists -> crashed between publish and unlink (cross-FS)
|
|
228
|
+
# NEVER delete either copy; mark failed and warn loudly with both paths.
|
|
229
|
+
if src_exists and dst_exists:
|
|
230
|
+
msg = (
|
|
231
|
+
f"both copies exist, remove one manually: source {src_display}, "
|
|
232
|
+
f"destination {dst_display}"
|
|
233
|
+
)
|
|
234
|
+
history.finish_op(
|
|
235
|
+
op.id,
|
|
236
|
+
MoveResult(
|
|
237
|
+
ok=False,
|
|
238
|
+
src=op.src_path,
|
|
239
|
+
dst=dst_path,
|
|
240
|
+
strategy=op.strategy or MoveStrategy.COPY_VERIFY,
|
|
241
|
+
message=msg,
|
|
242
|
+
),
|
|
243
|
+
)
|
|
244
|
+
history.record_event(
|
|
245
|
+
kind="recovery",
|
|
246
|
+
message=msg,
|
|
247
|
+
level="warning",
|
|
248
|
+
batch_id=op.batch_id,
|
|
249
|
+
op_id=op.id,
|
|
250
|
+
path=op.src_path,
|
|
251
|
+
)
|
|
252
|
+
return RecoveryAction(
|
|
253
|
+
op_id=op.id,
|
|
254
|
+
src_path=op.src_path,
|
|
255
|
+
dst_path=dst_path,
|
|
256
|
+
action_taken="conflict_warning",
|
|
257
|
+
message=msg,
|
|
258
|
+
)
|
|
259
|
+
|
|
260
|
+
# Case 4: neither exists -> removed/moved by external entity
|
|
261
|
+
msg = "source and destination missing"
|
|
262
|
+
history.finish_op(
|
|
263
|
+
op.id,
|
|
264
|
+
MoveResult(
|
|
265
|
+
ok=False,
|
|
266
|
+
src=op.src_path,
|
|
267
|
+
dst=dst_path,
|
|
268
|
+
strategy=None,
|
|
269
|
+
message=msg,
|
|
270
|
+
),
|
|
271
|
+
)
|
|
272
|
+
history.record_event(
|
|
273
|
+
kind="recovery",
|
|
274
|
+
message=msg,
|
|
275
|
+
level="info",
|
|
276
|
+
batch_id=op.batch_id,
|
|
277
|
+
op_id=op.id,
|
|
278
|
+
path=op.src_path,
|
|
279
|
+
)
|
|
280
|
+
return RecoveryAction(
|
|
281
|
+
op_id=op.id,
|
|
282
|
+
src_path=op.src_path,
|
|
283
|
+
dst_path=dst_path,
|
|
284
|
+
action_taken="marked_failed",
|
|
285
|
+
message=msg,
|
|
286
|
+
)
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
def reconcile(
|
|
290
|
+
history: History,
|
|
291
|
+
now: str | None = None,
|
|
292
|
+
planned_dirs: Sequence[Path] | None = None,
|
|
293
|
+
) -> list[RecoveryAction]:
|
|
294
|
+
"""Examines all pending operations per docs/05 section 5 recovery table."""
|
|
295
|
+
pending = history.pending_ops()
|
|
296
|
+
actions: list[RecoveryAction] = []
|
|
297
|
+
for op in pending:
|
|
298
|
+
actions.append(_reconcile_single_op(history, op, planned_dirs=planned_dirs))
|
|
299
|
+
return actions
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def reconcile_on_startup(
|
|
303
|
+
history: History,
|
|
304
|
+
startup_time_iso: str,
|
|
305
|
+
planned_dirs: Sequence[Path] | None = None,
|
|
306
|
+
) -> list[RecoveryAction]:
|
|
307
|
+
"""Reconciles only pending ops created strictly before startup_time_iso."""
|
|
308
|
+
startup_dt = _parse_iso(startup_time_iso)
|
|
309
|
+
pending = history.pending_ops()
|
|
310
|
+
actions: list[RecoveryAction] = []
|
|
311
|
+
for op in pending:
|
|
312
|
+
op_dt = _parse_iso(op.created_at)
|
|
313
|
+
if op_dt < startup_dt:
|
|
314
|
+
actions.append(_reconcile_single_op(history, op, planned_dirs=planned_dirs))
|
|
315
|
+
return actions
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
__all__ = ["RecoveryAction", "reconcile", "reconcile_on_startup"]
|