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.
Files changed (84) hide show
  1. clutterxp/__init__.py +4 -0
  2. clutterxp/cli/__init__.py +7 -0
  3. clutterxp/cli/app.py +251 -0
  4. clutterxp/cli/cmd_config.py +250 -0
  5. clutterxp/cli/cmd_doctor.py +449 -0
  6. clutterxp/cli/cmd_duplicates.py +253 -0
  7. clutterxp/cli/cmd_gui.py +22 -0
  8. clutterxp/cli/cmd_history.py +233 -0
  9. clutterxp/cli/cmd_init.py +76 -0
  10. clutterxp/cli/cmd_organize.py +226 -0
  11. clutterxp/cli/cmd_rules.py +540 -0
  12. clutterxp/cli/cmd_scan.py +109 -0
  13. clutterxp/cli/cmd_service.py +130 -0
  14. clutterxp/cli/cmd_undo.py +180 -0
  15. clutterxp/cli/cmd_watch.py +147 -0
  16. clutterxp/cli/errors.py +166 -0
  17. clutterxp/cli/render.py +390 -0
  18. clutterxp/config/__init__.py +40 -0
  19. clutterxp/config/jsonschema.py +12 -0
  20. clutterxp/config/loader.py +212 -0
  21. clutterxp/config/placeholders.py +79 -0
  22. clutterxp/config/runtime.py +30 -0
  23. clutterxp/config/schema.py +166 -0
  24. clutterxp/config/validate.py +226 -0
  25. clutterxp/config/writer.py +248 -0
  26. clutterxp/config.example.yaml +76 -0
  27. clutterxp/duplicates/__init__.py +22 -0
  28. clutterxp/duplicates/detector.py +438 -0
  29. clutterxp/duplicates/hashcache.py +149 -0
  30. clutterxp/duplicates/namenorm.py +45 -0
  31. clutterxp/duplicates/quarantine.py +196 -0
  32. clutterxp/duplicates/report.py +110 -0
  33. clutterxp/gui/__init__.py +1 -0
  34. clutterxp/gui/api.py +494 -0
  35. clutterxp/gui/app.py +205 -0
  36. clutterxp/gui/models_qt.py +544 -0
  37. clutterxp/gui/views/__init__.py +21 -0
  38. clutterxp/gui/views/dashboard.py +253 -0
  39. clutterxp/gui/views/duplicates.py +404 -0
  40. clutterxp/gui/views/folders.py +354 -0
  41. clutterxp/gui/views/history.py +281 -0
  42. clutterxp/gui/views/preview.py +277 -0
  43. clutterxp/gui/views/rules.py +527 -0
  44. clutterxp/gui/views/settings.py +172 -0
  45. clutterxp/gui/workers.py +147 -0
  46. clutterxp/history/__init__.py +23 -0
  47. clutterxp/history/db.py +174 -0
  48. clutterxp/history/pathcodec.py +42 -0
  49. clutterxp/history/recovery.py +318 -0
  50. clutterxp/history/schema.sql +43 -0
  51. clutterxp/history/service.py +493 -0
  52. clutterxp/history/undo.py +373 -0
  53. clutterxp/interfaces.py +164 -0
  54. clutterxp/locking.py +113 -0
  55. clutterxp/logging_setup.py +73 -0
  56. clutterxp/models.py +266 -0
  57. clutterxp/mover/__init__.py +26 -0
  58. clutterxp/mover/collision.py +46 -0
  59. clutterxp/mover/fsops.py +191 -0
  60. clutterxp/mover/safe_move.py +741 -0
  61. clutterxp/organizer.py +388 -0
  62. clutterxp/packaging/clutterxp.service +15 -0
  63. clutterxp/paths.py +112 -0
  64. clutterxp/planner.py +339 -0
  65. clutterxp/py.typed +0 -0
  66. clutterxp/rules/__init__.py +16 -0
  67. clutterxp/rules/engine.py +374 -0
  68. clutterxp/rules/matcher.py +222 -0
  69. clutterxp/rules/template.py +171 -0
  70. clutterxp/rules/tokenizer.py +118 -0
  71. clutterxp/safety.py +111 -0
  72. clutterxp/scanner.py +196 -0
  73. clutterxp/service_install.py +208 -0
  74. clutterxp/units.py +59 -0
  75. clutterxp/watch/__init__.py +37 -0
  76. clutterxp/watch/debounce.py +84 -0
  77. clutterxp/watch/events.py +259 -0
  78. clutterxp/watch/ignore.py +77 -0
  79. clutterxp/watch/service.py +662 -0
  80. clutterxp/watch/settle.py +170 -0
  81. clutterxp-1.1.0.dist-info/METADATA +149 -0
  82. clutterxp-1.1.0.dist-info/RECORD +84 -0
  83. clutterxp-1.1.0.dist-info/WHEEL +4 -0
  84. clutterxp-1.1.0.dist-info/entry_points.txt +6 -0
@@ -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
+ ]
@@ -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"]