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
|
@@ -0,0 +1,373 @@
|
|
|
1
|
+
"""Undo service: safe rollback of file operations."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import contextlib
|
|
6
|
+
import hashlib
|
|
7
|
+
import logging
|
|
8
|
+
import os
|
|
9
|
+
import stat
|
|
10
|
+
from collections.abc import Sequence
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from clutterxp import locking
|
|
14
|
+
from clutterxp.interfaces import History, Mover
|
|
15
|
+
from clutterxp.models import (
|
|
16
|
+
ClutterError,
|
|
17
|
+
CollisionPolicy,
|
|
18
|
+
CreateDestinations,
|
|
19
|
+
ErrorCode,
|
|
20
|
+
OperationRecord,
|
|
21
|
+
OpStatus,
|
|
22
|
+
UndoOutcome,
|
|
23
|
+
)
|
|
24
|
+
from clutterxp.mover.collision import split_name_ext
|
|
25
|
+
|
|
26
|
+
logger = logging.getLogger(__name__)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def _sha256_file(path: Path) -> str:
|
|
30
|
+
"""Compute SHA-256 digest of a file in 1 MiB chunks."""
|
|
31
|
+
h = hashlib.sha256()
|
|
32
|
+
with path.open("rb") as f:
|
|
33
|
+
while True:
|
|
34
|
+
chunk = f.read(1024 * 1024)
|
|
35
|
+
if not chunk:
|
|
36
|
+
break
|
|
37
|
+
h.update(chunk)
|
|
38
|
+
return h.hexdigest()
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _path_to_str(p: Path | None) -> str:
|
|
42
|
+
"""Safely format a Path to string, escaping non-UTF-8 surrogates for SQLite."""
|
|
43
|
+
if p is None:
|
|
44
|
+
return ""
|
|
45
|
+
return os.fsencode(p).decode("utf-8", errors="backslashreplace")
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class UndoService:
|
|
49
|
+
"""Safely undoes previously executed file operations.
|
|
50
|
+
|
|
51
|
+
Adheres to safety invariants S3 (no overwrite), S4 (no delete user files),
|
|
52
|
+
and S15 (independent operations: one refusal does not block the batch).
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
def __init__(self, history: History, mover: Mover, fs_lock_path: Path) -> None:
|
|
56
|
+
"""Initialize UndoService with history, mover, and lock file path."""
|
|
57
|
+
self.history = history
|
|
58
|
+
self.mover = mover
|
|
59
|
+
self.fs_lock_path = Path(fs_lock_path)
|
|
60
|
+
|
|
61
|
+
@staticmethod
|
|
62
|
+
def _matches_file_path(target: Path | None, query: Path) -> bool:
|
|
63
|
+
"""Check if target destination path matches the query path."""
|
|
64
|
+
if target is None:
|
|
65
|
+
return False
|
|
66
|
+
if target == query:
|
|
67
|
+
return True
|
|
68
|
+
try:
|
|
69
|
+
return target.resolve() == query.resolve()
|
|
70
|
+
except OSError:
|
|
71
|
+
return False
|
|
72
|
+
|
|
73
|
+
def undo(
|
|
74
|
+
self,
|
|
75
|
+
*,
|
|
76
|
+
op_id: int | None = None,
|
|
77
|
+
batch_id: int | None = None,
|
|
78
|
+
file_path: Path | None = None,
|
|
79
|
+
dry_run: bool = False,
|
|
80
|
+
on_conflict: str = "skip", # "skip" | "rename"
|
|
81
|
+
allow_modified: bool = False,
|
|
82
|
+
) -> Sequence[UndoOutcome]:
|
|
83
|
+
"""Undo file operations matching the specified selector.
|
|
84
|
+
|
|
85
|
+
Selectors are checked in priority order:
|
|
86
|
+
1. op_id: single operation
|
|
87
|
+
2. batch_id: all DONE operations in the batch (reverse id order)
|
|
88
|
+
3. file_path: latest DONE operation where dst_path == file_path
|
|
89
|
+
4. neither: all DONE operations in the last DONE batch (reverse id order)
|
|
90
|
+
|
|
91
|
+
Args:
|
|
92
|
+
op_id: Specific operation id to undo.
|
|
93
|
+
batch_id: Batch id whose DONE operations should be undone.
|
|
94
|
+
file_path: Current destination path of the file to undo.
|
|
95
|
+
dry_run: If True, evaluate checks without modifying filesystem or history.
|
|
96
|
+
on_conflict: "skip" (fail if occupied) or "rename" (restore as <stem> (restored)<ext>).
|
|
97
|
+
allow_modified: If True, waive check 3 (size/mtime/hash verification).
|
|
98
|
+
|
|
99
|
+
Returns:
|
|
100
|
+
Sequence of UndoOutcome objects.
|
|
101
|
+
"""
|
|
102
|
+
if on_conflict not in ("skip", "rename"):
|
|
103
|
+
msg = f"Invalid on_conflict policy: {on_conflict!r}. Must be 'skip' or 'rename'."
|
|
104
|
+
raise ValueError(msg)
|
|
105
|
+
|
|
106
|
+
ops_to_undo: list[OperationRecord] = []
|
|
107
|
+
|
|
108
|
+
if op_id is not None:
|
|
109
|
+
op = self.history.get_op(op_id)
|
|
110
|
+
if op is None:
|
|
111
|
+
return [
|
|
112
|
+
UndoOutcome(
|
|
113
|
+
op_id=op_id,
|
|
114
|
+
ok=False,
|
|
115
|
+
code=ErrorCode.UNDO_NOT_DONE,
|
|
116
|
+
message=f"Operation {op_id} not found",
|
|
117
|
+
)
|
|
118
|
+
]
|
|
119
|
+
ops_to_undo = [op]
|
|
120
|
+
elif batch_id is not None:
|
|
121
|
+
ops = self.history.list_ops(batch_id=batch_id, status=OpStatus.DONE, limit=100_000)
|
|
122
|
+
ops_to_undo = sorted(ops, key=lambda o: o.id, reverse=True)
|
|
123
|
+
elif file_path is not None:
|
|
124
|
+
done_ops = self.history.list_ops(status=OpStatus.DONE, limit=100_000)
|
|
125
|
+
matching = [op for op in done_ops if self._matches_file_path(op.dst_path, file_path)]
|
|
126
|
+
if not matching:
|
|
127
|
+
return []
|
|
128
|
+
latest_op = max(matching, key=lambda o: o.id)
|
|
129
|
+
ops_to_undo = [latest_op]
|
|
130
|
+
else:
|
|
131
|
+
last_bid = self.history.last_batch_id(with_status=OpStatus.DONE)
|
|
132
|
+
if last_bid is None:
|
|
133
|
+
return []
|
|
134
|
+
ops = self.history.list_ops(batch_id=last_bid, status=OpStatus.DONE, limit=100_000)
|
|
135
|
+
ops_to_undo = sorted(ops, key=lambda o: o.id, reverse=True)
|
|
136
|
+
|
|
137
|
+
if not ops_to_undo:
|
|
138
|
+
return []
|
|
139
|
+
|
|
140
|
+
if not dry_run:
|
|
141
|
+
self.history.begin_batch("undo", note=f"Undo {len(ops_to_undo)} operations")
|
|
142
|
+
|
|
143
|
+
outcomes: list[UndoOutcome] = []
|
|
144
|
+
for op in ops_to_undo:
|
|
145
|
+
if dry_run:
|
|
146
|
+
outcome = self._undo_single_op(
|
|
147
|
+
op,
|
|
148
|
+
dry_run=True,
|
|
149
|
+
on_conflict=on_conflict,
|
|
150
|
+
allow_modified=allow_modified,
|
|
151
|
+
)
|
|
152
|
+
else:
|
|
153
|
+
try:
|
|
154
|
+
with locking.fs_lock(self.fs_lock_path):
|
|
155
|
+
outcome = self._undo_single_op(
|
|
156
|
+
op,
|
|
157
|
+
dry_run=False,
|
|
158
|
+
on_conflict=on_conflict,
|
|
159
|
+
allow_modified=allow_modified,
|
|
160
|
+
)
|
|
161
|
+
except ClutterError as e:
|
|
162
|
+
outcome = UndoOutcome(
|
|
163
|
+
op_id=op.id,
|
|
164
|
+
ok=False,
|
|
165
|
+
code=e.code,
|
|
166
|
+
message=str(e),
|
|
167
|
+
)
|
|
168
|
+
outcomes.append(outcome)
|
|
169
|
+
|
|
170
|
+
return outcomes
|
|
171
|
+
|
|
172
|
+
def _undo_single_op(
|
|
173
|
+
self,
|
|
174
|
+
op: OperationRecord,
|
|
175
|
+
*,
|
|
176
|
+
dry_run: bool,
|
|
177
|
+
on_conflict: str,
|
|
178
|
+
allow_modified: bool,
|
|
179
|
+
) -> UndoOutcome:
|
|
180
|
+
"""Run checks 1-5 and optionally execute the restore for a single operation."""
|
|
181
|
+
# Check 1: status is DONE
|
|
182
|
+
if op.status != OpStatus.DONE:
|
|
183
|
+
return UndoOutcome(
|
|
184
|
+
op_id=op.id,
|
|
185
|
+
ok=False,
|
|
186
|
+
code=ErrorCode.UNDO_NOT_DONE,
|
|
187
|
+
message=(
|
|
188
|
+
f"Operation {op.id} has status {op.status.value}, "
|
|
189
|
+
f"expected {OpStatus.DONE.value}"
|
|
190
|
+
),
|
|
191
|
+
)
|
|
192
|
+
|
|
193
|
+
# Check 2: dst_path exists and is a regular file
|
|
194
|
+
if op.dst_path is None:
|
|
195
|
+
return UndoOutcome(
|
|
196
|
+
op_id=op.id,
|
|
197
|
+
ok=False,
|
|
198
|
+
code=ErrorCode.UNDO_DEST_MISSING,
|
|
199
|
+
message=f"Operation {op.id} destination path is missing",
|
|
200
|
+
)
|
|
201
|
+
|
|
202
|
+
try:
|
|
203
|
+
dst_st = op.dst_path.lstat()
|
|
204
|
+
except (FileNotFoundError, OSError):
|
|
205
|
+
return UndoOutcome(
|
|
206
|
+
op_id=op.id,
|
|
207
|
+
ok=False,
|
|
208
|
+
code=ErrorCode.UNDO_DEST_MISSING,
|
|
209
|
+
message=f"Destination {_path_to_str(op.dst_path)} does not exist",
|
|
210
|
+
)
|
|
211
|
+
|
|
212
|
+
if not stat.S_ISREG(dst_st.st_mode):
|
|
213
|
+
return UndoOutcome(
|
|
214
|
+
op_id=op.id,
|
|
215
|
+
ok=False,
|
|
216
|
+
code=ErrorCode.UNDO_DEST_MISSING,
|
|
217
|
+
message=f"Destination {_path_to_str(op.dst_path)} is not a regular file",
|
|
218
|
+
)
|
|
219
|
+
|
|
220
|
+
# Check 3: lstat(dst) size == op.size and mtime_ns == op.mtime_ns (and sha256)
|
|
221
|
+
size_mismatch = op.size is not None and dst_st.st_size != op.size
|
|
222
|
+
mtime_mismatch = op.mtime_ns is not None and dst_st.st_mtime_ns != op.mtime_ns
|
|
223
|
+
sha_mismatch = False
|
|
224
|
+
if op.sha256 is not None:
|
|
225
|
+
try:
|
|
226
|
+
cur_sha = _sha256_file(op.dst_path)
|
|
227
|
+
if cur_sha != op.sha256:
|
|
228
|
+
sha_mismatch = True
|
|
229
|
+
except OSError:
|
|
230
|
+
sha_mismatch = True
|
|
231
|
+
|
|
232
|
+
if (size_mismatch or mtime_mismatch or sha_mismatch) and not allow_modified:
|
|
233
|
+
details: list[str] = []
|
|
234
|
+
if size_mismatch:
|
|
235
|
+
details.append(f"size {dst_st.st_size} != recorded {op.size}")
|
|
236
|
+
if mtime_mismatch:
|
|
237
|
+
details.append(f"mtime_ns {dst_st.st_mtime_ns} != recorded {op.mtime_ns}")
|
|
238
|
+
if sha_mismatch:
|
|
239
|
+
details.append("hash mismatch")
|
|
240
|
+
dst_name = _path_to_str(op.dst_path)
|
|
241
|
+
return UndoOutcome(
|
|
242
|
+
op_id=op.id,
|
|
243
|
+
ok=False,
|
|
244
|
+
code=ErrorCode.UNDO_DEST_CHANGED,
|
|
245
|
+
message=f"Destination file {dst_name} has been modified ({', '.join(details)})",
|
|
246
|
+
)
|
|
247
|
+
|
|
248
|
+
# Check 4: original src_path does not exist
|
|
249
|
+
src_exists = os.path.lexists(op.src_path)
|
|
250
|
+
if src_exists:
|
|
251
|
+
if on_conflict == "skip":
|
|
252
|
+
return UndoOutcome(
|
|
253
|
+
op_id=op.id,
|
|
254
|
+
ok=False,
|
|
255
|
+
code=ErrorCode.UNDO_ORIGIN_OCCUPIED,
|
|
256
|
+
message=f"Original origin {_path_to_str(op.src_path)} is occupied",
|
|
257
|
+
)
|
|
258
|
+
# on_conflict == "rename"
|
|
259
|
+
stem, ext = split_name_ext(op.src_path.name)
|
|
260
|
+
target_name = f"{stem} (restored){ext}"
|
|
261
|
+
else:
|
|
262
|
+
target_name = op.src_path.name
|
|
263
|
+
|
|
264
|
+
target_parent = op.src_path.parent
|
|
265
|
+
target_path = target_parent / target_name
|
|
266
|
+
|
|
267
|
+
# Check 5: original parent directory exists / is writable
|
|
268
|
+
if target_parent.exists():
|
|
269
|
+
if not target_parent.is_dir():
|
|
270
|
+
return UndoOutcome(
|
|
271
|
+
op_id=op.id,
|
|
272
|
+
ok=False,
|
|
273
|
+
code=ErrorCode.DEST_NOT_WRITABLE,
|
|
274
|
+
message=(
|
|
275
|
+
f"Parent path {_path_to_str(target_parent)} exists but is not a directory"
|
|
276
|
+
),
|
|
277
|
+
)
|
|
278
|
+
if not os.access(target_parent, os.W_OK | os.X_OK):
|
|
279
|
+
return UndoOutcome(
|
|
280
|
+
op_id=op.id,
|
|
281
|
+
ok=False,
|
|
282
|
+
code=ErrorCode.DEST_NOT_WRITABLE,
|
|
283
|
+
message=f"Parent directory {_path_to_str(target_parent)} is not writable",
|
|
284
|
+
)
|
|
285
|
+
else:
|
|
286
|
+
curr = target_parent
|
|
287
|
+
while not curr.exists() and curr.parent != curr:
|
|
288
|
+
curr = curr.parent
|
|
289
|
+
if not curr.exists() or not curr.is_dir() or not os.access(curr, os.W_OK | os.X_OK):
|
|
290
|
+
return UndoOutcome(
|
|
291
|
+
op_id=op.id,
|
|
292
|
+
ok=False,
|
|
293
|
+
code=ErrorCode.DEST_NOT_WRITABLE,
|
|
294
|
+
message=(
|
|
295
|
+
f"Cannot recreate parent directory {_path_to_str(target_parent)}: "
|
|
296
|
+
f"ancestor {_path_to_str(curr)} is not writable"
|
|
297
|
+
),
|
|
298
|
+
)
|
|
299
|
+
|
|
300
|
+
# Dry-run evaluation: return outcome without any filesystem or history mutations
|
|
301
|
+
if dry_run:
|
|
302
|
+
if os.path.lexists(target_path):
|
|
303
|
+
return UndoOutcome(
|
|
304
|
+
op_id=op.id,
|
|
305
|
+
ok=False,
|
|
306
|
+
code=ErrorCode.COLLISION,
|
|
307
|
+
message=f"Restored destination {_path_to_str(target_path)} already exists",
|
|
308
|
+
)
|
|
309
|
+
return UndoOutcome(
|
|
310
|
+
op_id=op.id,
|
|
311
|
+
ok=True,
|
|
312
|
+
restored_to=target_path,
|
|
313
|
+
code=ErrorCode.NONE,
|
|
314
|
+
message=(
|
|
315
|
+
f"Would restore {_path_to_str(op.dst_path)} to {_path_to_str(target_path)}"
|
|
316
|
+
),
|
|
317
|
+
)
|
|
318
|
+
|
|
319
|
+
# Execute restore
|
|
320
|
+
parent_was_missing = not target_parent.exists()
|
|
321
|
+
|
|
322
|
+
move_res = self.mover.move_file(
|
|
323
|
+
op.dst_path,
|
|
324
|
+
target_parent,
|
|
325
|
+
new_name=target_name,
|
|
326
|
+
collision=CollisionPolicy.SKIP,
|
|
327
|
+
create=CreateDestinations.ALL,
|
|
328
|
+
)
|
|
329
|
+
|
|
330
|
+
if not move_res.ok:
|
|
331
|
+
return UndoOutcome(
|
|
332
|
+
op_id=op.id,
|
|
333
|
+
ok=False,
|
|
334
|
+
code=move_res.code,
|
|
335
|
+
message=move_res.message,
|
|
336
|
+
)
|
|
337
|
+
|
|
338
|
+
effective_restored_to = move_res.dst or target_path
|
|
339
|
+
dst_display = _path_to_str(op.dst_path)
|
|
340
|
+
restored_display = _path_to_str(effective_restored_to)
|
|
341
|
+
|
|
342
|
+
if parent_was_missing:
|
|
343
|
+
self.history.record_event(
|
|
344
|
+
"info",
|
|
345
|
+
f"Recreated missing destination directory {_path_to_str(target_parent)}",
|
|
346
|
+
op_id=op.id,
|
|
347
|
+
batch_id=op.batch_id,
|
|
348
|
+
path=target_parent,
|
|
349
|
+
)
|
|
350
|
+
|
|
351
|
+
self.history.mark_undone(op.id)
|
|
352
|
+
self.history.record_event(
|
|
353
|
+
"undo",
|
|
354
|
+
f"Restored {dst_display} to {restored_display}",
|
|
355
|
+
op_id=op.id,
|
|
356
|
+
batch_id=op.batch_id,
|
|
357
|
+
)
|
|
358
|
+
|
|
359
|
+
# Clean up op.created_dirs ONLY if empty, deepest first
|
|
360
|
+
if op.created_dirs:
|
|
361
|
+
sorted_dirs = sorted(op.created_dirs, key=lambda p: len(p.parts), reverse=True)
|
|
362
|
+
for d in sorted_dirs:
|
|
363
|
+
with contextlib.suppress(OSError):
|
|
364
|
+
os.rmdir(d) # noqa: PTH106
|
|
365
|
+
|
|
366
|
+
return UndoOutcome(
|
|
367
|
+
op_id=op.id,
|
|
368
|
+
ok=True,
|
|
369
|
+
restored_to=effective_restored_to,
|
|
370
|
+
)
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
__all__ = ["UndoService"]
|
clutterxp/interfaces.py
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
"""ClutterXP module interfaces (FROZEN).
|
|
2
|
+
|
|
3
|
+
These Protocols let agents build modules in parallel: each agent implements its
|
|
4
|
+
Protocol and tests against fakes of the others. Changing a signature requires a
|
|
5
|
+
CONTRACT_CHANGE request (see AGENTS.md).
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import Iterable, Protocol, Sequence, runtime_checkable
|
|
12
|
+
|
|
13
|
+
from .models import (
|
|
14
|
+
BatchResult,
|
|
15
|
+
CollisionPolicy,
|
|
16
|
+
CreateDestinations,
|
|
17
|
+
Decision,
|
|
18
|
+
DuplicateGroup,
|
|
19
|
+
ErrorCode,
|
|
20
|
+
FileInfo,
|
|
21
|
+
MoveResult,
|
|
22
|
+
OperationRecord,
|
|
23
|
+
OpStatus,
|
|
24
|
+
Plan,
|
|
25
|
+
ProgressCb,
|
|
26
|
+
RuleTrace,
|
|
27
|
+
UndoOutcome,
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@runtime_checkable
|
|
32
|
+
class RuleEngine(Protocol):
|
|
33
|
+
"""Pure: no filesystem writes, no file-content reads. stat() data comes in via FileInfo."""
|
|
34
|
+
|
|
35
|
+
def decide(self, file: FileInfo, *, folder: Path | None = None) -> Decision:
|
|
36
|
+
"""`folder` is the watched/scanned root; used to apply per-folder rule subsets."""
|
|
37
|
+
|
|
38
|
+
def trace(self, file: FileInfo) -> Sequence[RuleTrace]:
|
|
39
|
+
"""Explain every rule's match/non-match for one file (`rules test`)."""
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@runtime_checkable
|
|
43
|
+
class Mover(Protocol):
|
|
44
|
+
"""Filesystem primitive. Never deletes user data except the source after a verified publish."""
|
|
45
|
+
|
|
46
|
+
def move_file(
|
|
47
|
+
self,
|
|
48
|
+
src: Path,
|
|
49
|
+
dest_dir: Path,
|
|
50
|
+
*,
|
|
51
|
+
new_name: str | None = None,
|
|
52
|
+
collision: CollisionPolicy = CollisionPolicy.SKIP,
|
|
53
|
+
create: CreateDestinations = CreateDestinations.LEAF,
|
|
54
|
+
static_root: Path | None = None,
|
|
55
|
+
expect_size: int | None = None,
|
|
56
|
+
expect_mtime_ns: int | None = None,
|
|
57
|
+
progress: ProgressCb | None = None,
|
|
58
|
+
) -> MoveResult: ...
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@runtime_checkable
|
|
62
|
+
class History(Protocol):
|
|
63
|
+
def begin_batch(
|
|
64
|
+
self, command: str, folder: Path | None = None, note: str | None = None
|
|
65
|
+
) -> int: ...
|
|
66
|
+
|
|
67
|
+
def begin_op(self, batch_id: int, src: Path, rule_name: str | None, file: FileInfo) -> int:
|
|
68
|
+
"""Insert status=pending BEFORE any filesystem change. Must be durable on return."""
|
|
69
|
+
|
|
70
|
+
def finish_op(self, op_id: int, result: MoveResult) -> None:
|
|
71
|
+
"""Mark done/failed with final dst, strategy and created_dirs."""
|
|
72
|
+
|
|
73
|
+
def record_event(
|
|
74
|
+
self,
|
|
75
|
+
kind: str,
|
|
76
|
+
message: str,
|
|
77
|
+
*,
|
|
78
|
+
level: str = "info",
|
|
79
|
+
batch_id: int | None = None,
|
|
80
|
+
op_id: int | None = None,
|
|
81
|
+
path: Path | None = None,
|
|
82
|
+
) -> None: ...
|
|
83
|
+
|
|
84
|
+
def get_op(self, op_id: int) -> OperationRecord | None: ...
|
|
85
|
+
|
|
86
|
+
def list_ops(
|
|
87
|
+
self,
|
|
88
|
+
*,
|
|
89
|
+
batch_id: int | None = None,
|
|
90
|
+
status: OpStatus | None = None,
|
|
91
|
+
limit: int = 50,
|
|
92
|
+
since_iso: str | None = None,
|
|
93
|
+
rule_name: str | None = None,
|
|
94
|
+
path_contains: str | None = None,
|
|
95
|
+
) -> Sequence[OperationRecord]: ...
|
|
96
|
+
|
|
97
|
+
def last_batch_id(self, *, with_status: OpStatus = OpStatus.DONE) -> int | None: ...
|
|
98
|
+
|
|
99
|
+
def mark_undone(self, op_id: int) -> None: ...
|
|
100
|
+
|
|
101
|
+
def pending_ops(self) -> Sequence[OperationRecord]: ...
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
@runtime_checkable
|
|
105
|
+
class Organizer(Protocol):
|
|
106
|
+
"""The single facade used by the CLI, the watcher and the GUI."""
|
|
107
|
+
|
|
108
|
+
def plan(
|
|
109
|
+
self,
|
|
110
|
+
paths: Iterable[Path] | None = None,
|
|
111
|
+
*,
|
|
112
|
+
recursive: bool | None = None,
|
|
113
|
+
only_rules: Sequence[str] | None = None,
|
|
114
|
+
) -> Plan: ...
|
|
115
|
+
|
|
116
|
+
def apply(
|
|
117
|
+
self,
|
|
118
|
+
plan: Plan,
|
|
119
|
+
*,
|
|
120
|
+
command: str = "organize",
|
|
121
|
+
progress: ProgressCb | None = None,
|
|
122
|
+
) -> BatchResult: ...
|
|
123
|
+
|
|
124
|
+
def process_file(
|
|
125
|
+
self, path: Path, *, folder: Path | None = None, command: str = "watch"
|
|
126
|
+
) -> BatchResult:
|
|
127
|
+
"""Single-file path used by the watcher: decide -> plan -> apply, one batch of one op."""
|
|
128
|
+
|
|
129
|
+
def undo(
|
|
130
|
+
self,
|
|
131
|
+
*,
|
|
132
|
+
op_id: int | None = None,
|
|
133
|
+
batch_id: int | None = None,
|
|
134
|
+
dry_run: bool = False,
|
|
135
|
+
on_conflict: str = "skip",
|
|
136
|
+
allow_modified: bool = False,
|
|
137
|
+
) -> Sequence[UndoOutcome]: ...
|
|
138
|
+
|
|
139
|
+
def reload_config(self) -> None: ...
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
@runtime_checkable
|
|
143
|
+
class DuplicateDetector(Protocol):
|
|
144
|
+
def scan(
|
|
145
|
+
self,
|
|
146
|
+
folders: Sequence[Path],
|
|
147
|
+
*,
|
|
148
|
+
recursive: bool = True,
|
|
149
|
+
min_size: int = 1,
|
|
150
|
+
exclude: Sequence[str] = (),
|
|
151
|
+
jobs: int = 1,
|
|
152
|
+
potential: bool = True,
|
|
153
|
+
progress: ProgressCb | None = None,
|
|
154
|
+
) -> Sequence[DuplicateGroup]: ...
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
__all__ = [
|
|
158
|
+
"RuleEngine",
|
|
159
|
+
"Mover",
|
|
160
|
+
"History",
|
|
161
|
+
"Organizer",
|
|
162
|
+
"DuplicateDetector",
|
|
163
|
+
"ErrorCode",
|
|
164
|
+
]
|
clutterxp/locking.py
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"""Locking utilities: filesystem exclusive lock and watch lock."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import contextlib
|
|
6
|
+
import errno
|
|
7
|
+
import fcntl
|
|
8
|
+
import os
|
|
9
|
+
import time
|
|
10
|
+
from collections.abc import Generator
|
|
11
|
+
from contextlib import contextmanager
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
|
|
14
|
+
from clutterxp.models import ClutterError, ErrorCode
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _open_lock_file(lock_path: Path) -> int:
|
|
18
|
+
"""Open or create a lock file with 0600 permissions."""
|
|
19
|
+
lock_path.parent.mkdir(parents=True, exist_ok=True)
|
|
20
|
+
fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o600)
|
|
21
|
+
with contextlib.suppress(OSError):
|
|
22
|
+
lock_path.chmod(0o600)
|
|
23
|
+
return fd
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@contextmanager
|
|
27
|
+
def fs_lock(lock_path: Path, timeout: float = 10.0) -> Generator[None, None, None]:
|
|
28
|
+
"""Exclusive flock, timeout raises ClutterError(code=LOCK_TIMEOUT).
|
|
29
|
+
|
|
30
|
+
Lock file created 0600. Released by kernel on crash.
|
|
31
|
+
"""
|
|
32
|
+
fd = _open_lock_file(lock_path)
|
|
33
|
+
start = time.monotonic()
|
|
34
|
+
deadline = start + timeout
|
|
35
|
+
acquired = False
|
|
36
|
+
|
|
37
|
+
try:
|
|
38
|
+
while True:
|
|
39
|
+
try:
|
|
40
|
+
fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
|
41
|
+
acquired = True
|
|
42
|
+
break
|
|
43
|
+
except (BlockingIOError, OSError) as e:
|
|
44
|
+
err = getattr(e, "errno", None)
|
|
45
|
+
if err not in (errno.EACCES, errno.EAGAIN, errno.EWOULDBLOCK):
|
|
46
|
+
raise
|
|
47
|
+
if time.monotonic() >= deadline:
|
|
48
|
+
break
|
|
49
|
+
rem = deadline - time.monotonic()
|
|
50
|
+
if rem <= 0:
|
|
51
|
+
break
|
|
52
|
+
time.sleep(min(0.05, max(0.001, rem)))
|
|
53
|
+
|
|
54
|
+
if not acquired:
|
|
55
|
+
raise ClutterError(
|
|
56
|
+
f"Could not acquire filesystem lock at {lock_path} within {timeout}s",
|
|
57
|
+
code=ErrorCode.LOCK_TIMEOUT,
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
yield
|
|
61
|
+
finally:
|
|
62
|
+
if acquired:
|
|
63
|
+
with contextlib.suppress(OSError):
|
|
64
|
+
fcntl.flock(fd, fcntl.LOCK_UN)
|
|
65
|
+
with contextlib.suppress(OSError):
|
|
66
|
+
os.close(fd)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
@contextmanager
|
|
70
|
+
def watch_lock(lock_path: Path) -> Generator[None, None, None]:
|
|
71
|
+
"""Non-blocking flock. Raises ClutterError with PID of holder if locked.
|
|
72
|
+
|
|
73
|
+
Writes own PID to lock file. Lock file 0600.
|
|
74
|
+
"""
|
|
75
|
+
fd = _open_lock_file(lock_path)
|
|
76
|
+
acquired = False
|
|
77
|
+
|
|
78
|
+
try:
|
|
79
|
+
try:
|
|
80
|
+
fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
|
81
|
+
acquired = True
|
|
82
|
+
except (BlockingIOError, OSError) as e:
|
|
83
|
+
err = getattr(e, "errno", None)
|
|
84
|
+
if err in (errno.EACCES, errno.EAGAIN, errno.EWOULDBLOCK):
|
|
85
|
+
pid_holder = "unknown"
|
|
86
|
+
with contextlib.suppress(OSError), lock_path.open(encoding="utf-8") as f:
|
|
87
|
+
content = f.read().strip()
|
|
88
|
+
if content:
|
|
89
|
+
pid_holder = content
|
|
90
|
+
raise ClutterError(
|
|
91
|
+
f"Watch lock at {lock_path} is already held by PID {pid_holder}",
|
|
92
|
+
code=ErrorCode.LOCK_TIMEOUT,
|
|
93
|
+
) from None
|
|
94
|
+
raise
|
|
95
|
+
|
|
96
|
+
with contextlib.suppress(OSError):
|
|
97
|
+
os.ftruncate(fd, 0)
|
|
98
|
+
os.lseek(fd, 0, os.SEEK_SET)
|
|
99
|
+
os.write(fd, f"{os.getpid()}\n".encode())
|
|
100
|
+
os.fsync(fd)
|
|
101
|
+
|
|
102
|
+
yield
|
|
103
|
+
finally:
|
|
104
|
+
if acquired:
|
|
105
|
+
with contextlib.suppress(OSError):
|
|
106
|
+
os.ftruncate(fd, 0)
|
|
107
|
+
with contextlib.suppress(OSError):
|
|
108
|
+
fcntl.flock(fd, fcntl.LOCK_UN)
|
|
109
|
+
with contextlib.suppress(OSError):
|
|
110
|
+
os.close(fd)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
__all__ = ["fs_lock", "watch_lock"]
|