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
clutterxp/planner.py ADDED
@@ -0,0 +1,339 @@
1
+ """Planner module for evaluating rule decisions and building an execution Plan.
2
+
3
+ Converts FileInfo streams into PlannedAction entries, resolving destinations,
4
+ checking permissions and collision policies, and ensuring zero writes to disk.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import os
10
+ from collections.abc import Iterable, Sequence
11
+ from pathlib import Path
12
+
13
+ from clutterxp import safety
14
+ from clutterxp.config.runtime import RuntimeConfig
15
+ from clutterxp.interfaces import RuleEngine
16
+ from clutterxp.models import (
17
+ CollisionPolicy,
18
+ CreateDestinations,
19
+ DecisionKind,
20
+ ErrorCode,
21
+ FileInfo,
22
+ Plan,
23
+ PlannedAction,
24
+ PlanStatus,
25
+ SafetyRefusal,
26
+ )
27
+ from clutterxp.mover.collision import candidate_names
28
+
29
+
30
+ def build_plan(
31
+ infos: Iterable[FileInfo],
32
+ engine: RuleEngine,
33
+ config: RuntimeConfig | None = None,
34
+ *,
35
+ fs_check: bool = True,
36
+ folder: Path | None = None,
37
+ folders: Sequence[Path] | None = None,
38
+ ) -> Plan:
39
+ """Build a Plan from FileInfo objects using the given RuleEngine.
40
+
41
+ - Resolves destination path for matching rules.
42
+ - Safety checks destination against denylist (docs/09 S11).
43
+ - Checks watched folder containment unless allow_chain is True (docs/09 S9).
44
+ - Performs collision checks (skip vs rename) when fs_check is True.
45
+ - Pre-checks destination directory existence per create mode (never, leaf, all).
46
+ - Checks writability of destination directory.
47
+ - Performs ZERO disk writes and ZERO file content reads (Invariants S6, S7).
48
+ """
49
+ info_list = list(infos)
50
+ actions: list[PlannedAction] = []
51
+
52
+ if folders is not None:
53
+ plan_folders = tuple(folders)
54
+ elif folder is not None:
55
+ plan_folders = (folder,)
56
+ else:
57
+ plan_folders = tuple(sorted({fi.path.parent for fi in info_list}))
58
+
59
+ for info in info_list:
60
+ decision = engine.decide(info, folder=folder)
61
+
62
+ if decision.kind == DecisionKind.NO_MATCH:
63
+ actions.append(
64
+ PlannedAction(
65
+ file=info,
66
+ status=PlanStatus.NO_MATCH,
67
+ decision=decision,
68
+ dest_path=None,
69
+ code=ErrorCode.NONE,
70
+ message=decision.reason or "No rule matched",
71
+ )
72
+ )
73
+ continue
74
+
75
+ if decision.kind == DecisionKind.AMBIGUOUS:
76
+ cand_names = ", ".join(c.rule_name for c in decision.candidates)
77
+ actions.append(
78
+ PlannedAction(
79
+ file=info,
80
+ status=PlanStatus.AMBIGUOUS,
81
+ decision=decision,
82
+ dest_path=None,
83
+ code=ErrorCode.NONE,
84
+ message=f"Ambiguous match across rules: {cand_names}",
85
+ )
86
+ )
87
+ continue
88
+
89
+ if decision.kind == DecisionKind.IGNORED:
90
+ actions.append(
91
+ PlannedAction(
92
+ file=info,
93
+ status=PlanStatus.IGNORED,
94
+ decision=decision,
95
+ dest_path=None,
96
+ code=ErrorCode.NONE,
97
+ message=decision.reason or "Ignored",
98
+ )
99
+ )
100
+ continue
101
+
102
+ # DecisionKind.MATCH
103
+ hit = decision.hit
104
+ if hit is None:
105
+ actions.append(
106
+ PlannedAction(
107
+ file=info,
108
+ status=PlanStatus.BLOCKED,
109
+ decision=decision,
110
+ dest_path=None,
111
+ code=ErrorCode.UNKNOWN,
112
+ message="Match decision without rule hit",
113
+ )
114
+ )
115
+ continue
116
+
117
+ dest_dir = hit.dest_dir
118
+ dest_path = dest_dir / info.name
119
+
120
+ # Safety check destination
121
+ try:
122
+ safety.check_destination(dest_path)
123
+ except SafetyRefusal as e:
124
+ actions.append(
125
+ PlannedAction(
126
+ file=info,
127
+ status=PlanStatus.BLOCKED,
128
+ decision=decision,
129
+ dest_path=dest_path,
130
+ code=ErrorCode.DEST_INVALID,
131
+ message=str(e),
132
+ )
133
+ )
134
+ continue
135
+
136
+ # Invariant S9: Destination inside watched folder without allow_chain
137
+ if config is not None and not config.settings.allow_chain:
138
+ dest_resolved = dest_path.resolve()
139
+ is_inside_watch = False
140
+ for w in config.watch_entries:
141
+ try:
142
+ w_resolved = Path(w.path).resolve()
143
+ dest_resolved.relative_to(w_resolved)
144
+ is_inside_watch = True
145
+ break
146
+ except (ValueError, OSError):
147
+ pass
148
+ if is_inside_watch:
149
+ actions.append(
150
+ PlannedAction(
151
+ file=info,
152
+ status=PlanStatus.BLOCKED,
153
+ decision=decision,
154
+ dest_path=dest_path,
155
+ code=ErrorCode.DEST_INVALID,
156
+ message="Destination is inside a watched folder (allow_chain is False)",
157
+ )
158
+ )
159
+ continue
160
+
161
+ # Precondition: Destination directory is not source's own directory (no-op)
162
+ try:
163
+ if dest_path.resolve() == info.path.resolve():
164
+ actions.append(
165
+ PlannedAction(
166
+ file=info,
167
+ status=PlanStatus.BLOCKED,
168
+ decision=decision,
169
+ dest_path=dest_path,
170
+ code=ErrorCode.DEST_INVALID,
171
+ message="Destination directory is source's own directory (no-op)",
172
+ )
173
+ )
174
+ continue
175
+ except OSError:
176
+ pass
177
+
178
+ if not fs_check:
179
+ actions.append(
180
+ PlannedAction(
181
+ file=info,
182
+ status=PlanStatus.WILL_MOVE,
183
+ decision=decision,
184
+ dest_path=dest_path,
185
+ code=ErrorCode.NONE,
186
+ message="",
187
+ )
188
+ )
189
+ continue
190
+
191
+ # Check CreateDestinations policy
192
+ create_policy = hit.create
193
+ if create_policy == CreateDestinations.NEVER:
194
+ if not dest_dir.exists() or not dest_dir.is_dir():
195
+ actions.append(
196
+ PlannedAction(
197
+ file=info,
198
+ status=PlanStatus.BLOCKED,
199
+ decision=decision,
200
+ dest_path=dest_path,
201
+ code=ErrorCode.DEST_MISSING,
202
+ message=(
203
+ f"Destination directory '{dest_dir}' does not exist (create: never)"
204
+ ),
205
+ )
206
+ )
207
+ continue
208
+ elif create_policy == CreateDestinations.LEAF:
209
+ static_root = hit.static_root
210
+ if static_root is not None:
211
+ if not static_root.exists() and not static_root.parent.exists():
212
+ actions.append(
213
+ PlannedAction(
214
+ file=info,
215
+ status=PlanStatus.BLOCKED,
216
+ decision=decision,
217
+ dest_path=dest_path,
218
+ code=ErrorCode.DEST_MISSING,
219
+ message=(
220
+ f"Static root parent '{static_root.parent}' does not exist "
221
+ "(create: leaf)"
222
+ ),
223
+ )
224
+ )
225
+ continue
226
+ # If dest_dir is not relative to static_root, ensure its parent exists
227
+ try:
228
+ dest_dir.relative_to(static_root)
229
+ except ValueError:
230
+ if not dest_dir.exists() and not dest_dir.parent.exists():
231
+ actions.append(
232
+ PlannedAction(
233
+ file=info,
234
+ status=PlanStatus.BLOCKED,
235
+ decision=decision,
236
+ dest_path=dest_path,
237
+ code=ErrorCode.DEST_MISSING,
238
+ message=(
239
+ f"Destination parent '{dest_dir.parent}' does not exist "
240
+ "(create: leaf)"
241
+ ),
242
+ )
243
+ )
244
+ continue
245
+ else:
246
+ if not dest_dir.exists() and not dest_dir.parent.exists():
247
+ actions.append(
248
+ PlannedAction(
249
+ file=info,
250
+ status=PlanStatus.BLOCKED,
251
+ decision=decision,
252
+ dest_path=dest_path,
253
+ code=ErrorCode.DEST_MISSING,
254
+ message=(
255
+ f"Destination parent '{dest_dir.parent}' does not exist "
256
+ "(create: leaf)"
257
+ ),
258
+ )
259
+ )
260
+ continue
261
+
262
+ # Check writability of existing ancestor
263
+ check_dir = dest_dir
264
+ while not check_dir.exists() and check_dir != check_dir.parent:
265
+ check_dir = check_dir.parent
266
+ if check_dir.exists() and not os.access(check_dir, os.W_OK | os.X_OK):
267
+ actions.append(
268
+ PlannedAction(
269
+ file=info,
270
+ status=PlanStatus.BLOCKED,
271
+ decision=decision,
272
+ dest_path=dest_path,
273
+ code=ErrorCode.DEST_NOT_WRITABLE,
274
+ message=f"Destination directory '{check_dir}' is not writable",
275
+ )
276
+ )
277
+ continue
278
+
279
+ # Collision pre-check
280
+ if dest_path.exists():
281
+ if hit.collision == CollisionPolicy.SKIP:
282
+ actions.append(
283
+ PlannedAction(
284
+ file=info,
285
+ status=PlanStatus.BLOCKED,
286
+ decision=decision,
287
+ dest_path=dest_path,
288
+ code=ErrorCode.COLLISION,
289
+ message=f"Destination path '{dest_path}' already exists (collision: skip)",
290
+ )
291
+ )
292
+ continue
293
+ elif hit.collision == CollisionPolicy.RENAME:
294
+ renamed_dest: Path | None = None
295
+ for cand_name in candidate_names(info.name):
296
+ cand_path = dest_dir / cand_name
297
+ if not cand_path.exists():
298
+ renamed_dest = cand_path
299
+ break
300
+ if renamed_dest is not None:
301
+ actions.append(
302
+ PlannedAction(
303
+ file=info,
304
+ status=PlanStatus.WILL_MOVE_RENAMED,
305
+ decision=decision,
306
+ dest_path=renamed_dest,
307
+ code=ErrorCode.NONE,
308
+ message=f"Collision detected; will rename to '{renamed_dest.name}'",
309
+ )
310
+ )
311
+ continue
312
+ else:
313
+ actions.append(
314
+ PlannedAction(
315
+ file=info,
316
+ status=PlanStatus.BLOCKED,
317
+ decision=decision,
318
+ dest_path=dest_path,
319
+ code=ErrorCode.COLLISION,
320
+ message="All collision rename candidates exhausted",
321
+ )
322
+ )
323
+ continue
324
+
325
+ actions.append(
326
+ PlannedAction(
327
+ file=info,
328
+ status=PlanStatus.WILL_MOVE,
329
+ decision=decision,
330
+ dest_path=dest_path,
331
+ code=ErrorCode.NONE,
332
+ message="",
333
+ )
334
+ )
335
+
336
+ return Plan(folders=plan_folders, actions=tuple(actions))
337
+
338
+
339
+ __all__ = ["build_plan"]
clutterxp/py.typed ADDED
File without changes
@@ -0,0 +1,16 @@
1
+ """Rule engine: tokenization, matching, template expansion, and decision making."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+ from clutterxp.config.schema import RuleSpec, Settings
8
+ from clutterxp.rules.engine import RuleEngineImpl
9
+
10
+
11
+ def build_engine(rules: list[RuleSpec], settings: Settings, **kwargs: Any) -> RuleEngineImpl:
12
+ """Factory. A01's RuntimeConfig will be adapted here when merged."""
13
+ return RuleEngineImpl(rules, settings, **kwargs)
14
+
15
+
16
+ __all__ = ["RuleEngineImpl", "build_engine"]