@mokuyoaxis/agent-guard 0.2.7 → 0.2.9
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.
- package/CONTRIBUTING.md +13 -0
- package/README.md +37 -27
- package/README.zh-CN.md +32 -24
- package/adapters/INTEGRATION.md +9 -3
- package/adapters/mcp/doctor.py +326 -0
- package/adapters/mcp/operations.py +33 -3
- package/adapters/mcp/server.py +17 -0
- package/core/cleanup.py +33 -11
- package/core/cleanup_groups.py +329 -0
- package/core/policy.py +20 -3
- package/docs/README.md +38 -13
- package/docs/design/architecture.md +63 -14
- package/docs/design/compatibility.md +121 -5
- package/docs/guides/cleanup-plan.md +97 -0
- package/docs/guides/getting-started.md +7 -6
- package/docs/guides/harness-capabilities.md +21 -4
- package/docs/guides/mcp.md +202 -11
- package/docs/releases/release-notes-0.2.8.md +172 -0
- package/docs/releases/release-notes-0.2.9.md +68 -0
- package/docs/releases/unreleased.md +198 -1
- package/doctor.py +25 -1
- package/live_sentinel.py +1 -1
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +27 -1
- package/skills/delete-guard/scripts/cleanup.py +48 -3
|
@@ -17,7 +17,8 @@ import threading
|
|
|
17
17
|
|
|
18
18
|
ROOT = Path(__file__).resolve().parents[2]
|
|
19
19
|
SCRIPTS = ROOT / "skills" / "delete-guard" / "scripts"
|
|
20
|
-
|
|
20
|
+
GROUP_TOOLS = frozenset(("cleanup_discover", "cleanup_measure"))
|
|
21
|
+
TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan")) | GROUP_TOOLS
|
|
21
22
|
MAX_PATHS = 1000
|
|
22
23
|
TXID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*\Z")
|
|
23
24
|
|
|
@@ -76,7 +77,9 @@ class Operations:
|
|
|
76
77
|
if not isinstance(arguments, dict):
|
|
77
78
|
raise InvalidArguments("tool arguments must be an object")
|
|
78
79
|
allowed = {"safe_delete": {"paths", "dry_run"}, "restore": {"txid"},
|
|
79
|
-
"status": {"tail"}, "transactions": set(), "gc_plan": set()
|
|
80
|
+
"status": {"tail"}, "transactions": set(), "gc_plan": set(),
|
|
81
|
+
"cleanup_discover": {"scopes", "max_entries", "max_depth"},
|
|
82
|
+
"cleanup_measure": {"scopes", "max_entries", "max_depth"}}[name]
|
|
80
83
|
if set(arguments) - allowed:
|
|
81
84
|
raise InvalidArguments("unsupported tool argument")
|
|
82
85
|
result = dict(arguments)
|
|
@@ -102,6 +105,19 @@ class Operations:
|
|
|
102
105
|
if type(result.get("tail", 10)) is not int or not 0 <= result.get("tail", 10) <= 100:
|
|
103
106
|
raise InvalidArguments("tail must be an integer between 0 and 100")
|
|
104
107
|
result["tail"] = result.get("tail", 10)
|
|
108
|
+
elif name in GROUP_TOOLS:
|
|
109
|
+
scopes = result.get("scopes", [])
|
|
110
|
+
if (not isinstance(scopes, list) or len(scopes) > 64
|
|
111
|
+
or (name == "cleanup_measure" and not scopes)
|
|
112
|
+
or any(not isinstance(path, str) or not path or "\0" in path for path in scopes)):
|
|
113
|
+
raise InvalidArguments("scopes must be at most 64 nonempty literal directory paths; measure requires scopes")
|
|
114
|
+
result["scopes"] = scopes
|
|
115
|
+
for field, maximum in (("max_entries", 10000 if name == "cleanup_discover" else 20000),
|
|
116
|
+
("max_depth", 4 if name == "cleanup_discover" else 32)):
|
|
117
|
+
value = result.get(field, maximum)
|
|
118
|
+
if type(value) is not int or not 1 <= value <= maximum:
|
|
119
|
+
raise InvalidArguments(field + " must be an integer between 1 and " + str(maximum))
|
|
120
|
+
result[field] = value
|
|
105
121
|
return result
|
|
106
122
|
|
|
107
123
|
def _quarantine_overlap(self, paths):
|
|
@@ -136,8 +152,14 @@ class Operations:
|
|
|
136
152
|
command = ["restore.py", "list", "--json"]
|
|
137
153
|
elif name == "status":
|
|
138
154
|
command = ["status.py", "--json", "--tail", str(args["tail"])]
|
|
139
|
-
|
|
155
|
+
elif name == "gc_plan":
|
|
140
156
|
command = ["gc.py", "--json"]
|
|
157
|
+
else:
|
|
158
|
+
command = ["cleanup.py", "--json", "--discover" if name == "cleanup_discover" else "--measure",
|
|
159
|
+
"--max-entries", str(args["max_entries"]), "--max-depth", str(args["max_depth"])]
|
|
160
|
+
# Equals syntax keeps even an option-looking literal inside its
|
|
161
|
+
# value, without changing the server's fixed workspace binding.
|
|
162
|
+
command += ["--scope=" + scope for scope in args["scopes"]]
|
|
141
163
|
|
|
142
164
|
# Serialize calls in this server, without changing process cwd or
|
|
143
165
|
# environment. Other participating processes share Core admission.
|
|
@@ -168,6 +190,14 @@ class Operations:
|
|
|
168
190
|
return self._failure(name, "MCP_CLI_PROTOCOL_ERROR",
|
|
169
191
|
"CLI did not return a JSON object; inspect recovery state before retrying",
|
|
170
192
|
exit_code=child.returncode, may_have_changed=mutating)
|
|
193
|
+
if name in GROUP_TOOLS and child.returncode in (0, 1):
|
|
194
|
+
expected = "cleanup_group_discovery/v1" if name == "cleanup_discover" else "cleanup_group_measurement/v1"
|
|
195
|
+
if result.get("schema") != expected:
|
|
196
|
+
return self._failure(name, "MCP_CLI_PROTOCOL_ERROR", "Unexpected cleanup observation schema",
|
|
197
|
+
exit_code=child.returncode)
|
|
198
|
+
partial = (not result["coverage"]["frontier_complete"] if name == "cleanup_discover"
|
|
199
|
+
else any(not row["size_complete"] for row in result["scopes"]))
|
|
200
|
+
return {"tool": name, "ok": True, "partial": partial, "exit_code": child.returncode, "result": result}
|
|
171
201
|
# Preserve all existing CLI evidence, including txids/moved paths on
|
|
172
202
|
# partial failures. A nonzero exit never means 'nothing changed'.
|
|
173
203
|
return {"tool": name, "ok": child.returncode == 0,
|
package/adapters/mcp/server.py
CHANGED
|
@@ -22,6 +22,9 @@ INSTRUCTIONS = (
|
|
|
22
22
|
"or retry an uncertain mutation automatically. Large batches and operator-only actions "
|
|
23
23
|
"remain in the existing CLI workflow. GC here is preview only. These tools do not "
|
|
24
24
|
"intercept other shell or editor operations."
|
|
25
|
+
" Use cleanup_discover for a bounded directory overview and cleanup_measure for explicit scopes. "
|
|
26
|
+
"Their observations never grant execution permission. A successful call with partial=true "
|
|
27
|
+
"still has incomplete coverage or unknown whole sizes; inspect those fields and use exact scopes."
|
|
25
28
|
)
|
|
26
29
|
|
|
27
30
|
TOOL_DEFINITIONS = {
|
|
@@ -49,6 +52,20 @@ TOOL_DEFINITIONS = {
|
|
|
49
52
|
"description": "Preview existing quarantine transaction GC eligibility and retained space. This tool never executes GC or deletes recovery copies. Execution remains an explicit operator CLI action.",
|
|
50
53
|
"properties": {}, "required": [], "read_only": True, "destructive": False,
|
|
51
54
|
},
|
|
55
|
+
"cleanup_discover": {
|
|
56
|
+
"description": "Read-only bounded directory overview in the fixed workspace. Optional scopes continue discovery below exact directories. Runtime/cache ownership labels are hints, not proof of obsolescence. Sizes remain unknown; inspect coverage/unexpanded and partial even when ok=true. No executable plan or deletion permission.",
|
|
57
|
+
"properties": {"scopes": {"type": "array", "items": {"type": "string", "minLength": 1}, "maxItems": 64},
|
|
58
|
+
"max_entries": {"type": "integer", "minimum": 1, "maximum": 10000, "default": 10000},
|
|
59
|
+
"max_depth": {"type": "integer", "minimum": 1, "maximum": 4, "default": 4}},
|
|
60
|
+
"required": [], "read_only": True, "destructive": False,
|
|
61
|
+
},
|
|
62
|
+
"cleanup_measure": {
|
|
63
|
+
"description": "Read-only metadata measurement of explicit non-overlapping directory scopes below the same workspace. Does not follow links or traverse protected subtrees. size_bytes=null means unknown, not zero; observed_bytes excludes protected data. Core projection is not approval. No plan_id, deletion, restore or GC execution.",
|
|
64
|
+
"properties": {"scopes": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "maxItems": 64},
|
|
65
|
+
"max_entries": {"type": "integer", "minimum": 1, "maximum": 20000, "default": 20000},
|
|
66
|
+
"max_depth": {"type": "integer", "minimum": 1, "maximum": 32, "default": 32}},
|
|
67
|
+
"required": ["scopes"], "read_only": True, "destructive": False,
|
|
68
|
+
},
|
|
52
69
|
}
|
|
53
70
|
|
|
54
71
|
|
package/core/cleanup.py
CHANGED
|
@@ -113,6 +113,7 @@ def plan_cleanup(
|
|
|
113
113
|
physical_protection.append(os.path.relpath(physical, root).replace(os.sep, "/"))
|
|
114
114
|
protect = sorted(set(protect + physical_protection))
|
|
115
115
|
trash = os.path.abspath(os.environ.get("AGENT_GUARD_TRASH", os.path.join(root, TRASH_DIRNAME)))
|
|
116
|
+
trash_physical = os.path.realpath(trash)
|
|
116
117
|
if classifier.inside_path(trash, root):
|
|
117
118
|
protect = sorted(set(protect + [os.path.relpath(trash, root).replace(os.sep, "/")]))
|
|
118
119
|
ctx = policy.PolicyContext(workspace=root, trash_root=trash, base_dir=root,
|
|
@@ -127,7 +128,7 @@ def plan_cleanup(
|
|
|
127
128
|
if record not in errors:
|
|
128
129
|
errors.append(record)
|
|
129
130
|
|
|
130
|
-
def visit(relative: str, depth: int) -> _Node:
|
|
131
|
+
def visit(relative: str, depth: int, entry=None) -> _Node:
|
|
131
132
|
nonlocal examined
|
|
132
133
|
node = _Node(relative)
|
|
133
134
|
nodes.append(node)
|
|
@@ -144,12 +145,23 @@ def plan_cleanup(
|
|
|
144
145
|
problem(node, "PROTECTED_ALIAS_REQUIRES_EXPLICIT_PROTECT")
|
|
145
146
|
else:
|
|
146
147
|
try:
|
|
147
|
-
info = os.lstat(absolute)
|
|
148
|
+
info = entry.stat(follow_symlinks=False) if entry is not None else os.lstat(absolute)
|
|
148
149
|
node.signature = [info.st_dev, info.st_ino, info.st_mode,
|
|
149
150
|
info.st_size, info.st_mtime_ns, info.st_ctime_ns]
|
|
151
|
+
# Parents were checked before traversal and directory links
|
|
152
|
+
# are never followed. Ordinary files can reuse that location
|
|
153
|
+
# without repeating full boundary/type checks for every leaf.
|
|
154
|
+
# Keep the original classifier for directories, links and
|
|
155
|
+
# special roots (including an invalid trash path below a file).
|
|
156
|
+
ordinary_file = (stat.S_ISREG(info.st_mode)
|
|
157
|
+
and not classifier.protected_ancestor_root(absolute)
|
|
158
|
+
and not (_under(trash, absolute)
|
|
159
|
+
or _under(trash_physical, absolute)))
|
|
150
160
|
spec = (classifier.classify_paths(["./" + relative], root, root, trash)[0]
|
|
151
|
-
if relative != "." else None)
|
|
152
|
-
physical = os.path.relpath(
|
|
161
|
+
if relative != "." and not ordinary_file else None)
|
|
162
|
+
physical = os.path.relpath(
|
|
163
|
+
absolute if ordinary_file else os.path.realpath(absolute), root
|
|
164
|
+
).replace(os.sep, "/")
|
|
153
165
|
if ((spec and spec.protected) or set(physical.split("/")) & PROTECTED_NAMES
|
|
154
166
|
or any(_under(physical, p) for p in protect)
|
|
155
167
|
or (stat.S_ISLNK(info.st_mode)
|
|
@@ -160,20 +172,21 @@ def plan_cleanup(
|
|
|
160
172
|
if depth >= max_depth:
|
|
161
173
|
problem(node, "DEPTH_LIMIT_REACHED")
|
|
162
174
|
else:
|
|
163
|
-
|
|
175
|
+
children = []
|
|
164
176
|
with os.scandir(absolute) as entries:
|
|
165
|
-
for
|
|
166
|
-
if examined + len(
|
|
177
|
+
for child_entry in entries:
|
|
178
|
+
if examined + len(children) >= max_entries:
|
|
167
179
|
problem(node, "ENTRY_LIMIT_REACHED")
|
|
168
180
|
break
|
|
169
|
-
|
|
170
|
-
for
|
|
181
|
+
children.append(child_entry)
|
|
182
|
+
for child_entry in sorted(children, key=lambda item: item.name):
|
|
171
183
|
if examined >= max_entries:
|
|
172
184
|
problem(node, "ENTRY_LIMIT_REACHED")
|
|
173
185
|
break
|
|
186
|
+
name = child_entry.name
|
|
174
187
|
examined += 1
|
|
175
188
|
child = visit(name if relative == "." else relative + "/" + name,
|
|
176
|
-
depth + 1)
|
|
189
|
+
depth + 1, child_entry)
|
|
177
190
|
node.children.append(child)
|
|
178
191
|
node.files.update(child.files)
|
|
179
192
|
node.complete &= child.complete
|
|
@@ -206,6 +219,12 @@ def plan_cleanup(
|
|
|
206
219
|
parts = path.split("/")
|
|
207
220
|
tracked_ancestors.update("/".join(parts[:i]) for i in range(1, len(parts)))
|
|
208
221
|
|
|
222
|
+
def git_ignored(workspace, absolute):
|
|
223
|
+
return os.path.relpath(absolute, root).replace(os.sep, "/") in ignored
|
|
224
|
+
|
|
225
|
+
def regenerable(specs, context):
|
|
226
|
+
return policy._regenerable(specs, context, git_ignored)
|
|
227
|
+
|
|
209
228
|
def row(node: _Node, category: str, reason: str) -> Dict[str, Any]:
|
|
210
229
|
result = {
|
|
211
230
|
"path": node.path, "kind": node.kind, "category": category,
|
|
@@ -220,7 +239,10 @@ def plan_cleanup(
|
|
|
220
239
|
# Concrete, relative spelling also used by the execution CLI.
|
|
221
240
|
spelling = "./" + node.path
|
|
222
241
|
specs = classifier.classify_paths([spelling], root, root, trash)
|
|
223
|
-
verdict = policy.
|
|
242
|
+
verdict = policy._decide_path_batch(
|
|
243
|
+
specs, ctx, recursive=True,
|
|
244
|
+
config_loader=lambda workspace: delete_config,
|
|
245
|
+
regenerable_check=regenerable)
|
|
224
246
|
result["policy_code"] = verdict.code
|
|
225
247
|
literal = (not specs[0].wildcard and not specs[0].indeterminable
|
|
226
248
|
and specs[0].resolved == os.path.join(root, node.path))
|
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
"""Read-only cleanup groups; observation never grants deletion permission.
|
|
2
|
+
|
|
3
|
+
Discovery is a bounded directory frontier. Measurement keeps the original
|
|
4
|
+
workspace and omits protected subtrees. Neither produces an executable plan.
|
|
5
|
+
"""
|
|
6
|
+
from collections import Counter
|
|
7
|
+
import errno
|
|
8
|
+
import hashlib
|
|
9
|
+
import heapq
|
|
10
|
+
import json
|
|
11
|
+
import os
|
|
12
|
+
from pathlib import Path
|
|
13
|
+
import stat
|
|
14
|
+
|
|
15
|
+
from core import classifier, policy
|
|
16
|
+
from core.cleanup import PROTECTED_NAMES, _git_facts
|
|
17
|
+
from core.delete_config import load_config
|
|
18
|
+
|
|
19
|
+
TAG = b'Signature: 8a477f597d28d172789f06886806bc55'
|
|
20
|
+
LABELS = {'protected': '受保护', 'runtime': '运行环境', 'managed_cache': '应用管理缓存',
|
|
21
|
+
'cache_hint': '缓存提示', 'artifact': '构建工件', 'link': '未跟随链接'}
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def under(path, parent):
|
|
25
|
+
return parent == '.' or path == parent or path.startswith(parent + '/')
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def signature(info):
|
|
29
|
+
return [info.st_dev, info.st_ino, info.st_mode, info.st_size, info.st_mtime_ns, info.st_ctime_ns]
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def positive(value):
|
|
33
|
+
if type(value) is not int or value < 1:
|
|
34
|
+
raise ValueError('scan limits must be positive integers')
|
|
35
|
+
return value
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class GroupScanner:
|
|
39
|
+
def __init__(self, workspace):
|
|
40
|
+
self.root = Path(workspace).resolve(strict=True)
|
|
41
|
+
if not self.root.is_dir() or classifier.protected_ancestor_root(str(self.root)):
|
|
42
|
+
raise ValueError('workspace must be an existing non-root project directory')
|
|
43
|
+
self.config = load_config(str(self.root))
|
|
44
|
+
self.guard_config = policy.GuardConfig.from_env()
|
|
45
|
+
self.protect = set(PROTECTED_NAMES) | {name.replace(os.sep, '/') for name in self.config.protected_paths}
|
|
46
|
+
self.trash = os.path.abspath(os.environ.get('AGENT_GUARD_TRASH', self.root / '.agent-trash'))
|
|
47
|
+
if classifier.inside_path(self.trash, str(self.root)):
|
|
48
|
+
relative = os.path.relpath(self.trash, self.root).replace(os.sep, '/')
|
|
49
|
+
self.protect.add(relative.split('/')[0])
|
|
50
|
+
for name in list(self.protect):
|
|
51
|
+
physical = os.path.realpath(self.root / name)
|
|
52
|
+
if classifier.inside_path(physical, str(self.root)):
|
|
53
|
+
self.protect.add(os.path.relpath(physical, self.root).replace(os.sep, '/'))
|
|
54
|
+
self.marker_bytes = 0
|
|
55
|
+
|
|
56
|
+
def protected(self, relative):
|
|
57
|
+
return bool(set(relative.split('/')) & PROTECTED_NAMES) or any(under(relative, path) for path in self.protect)
|
|
58
|
+
|
|
59
|
+
def marker(self, relative, name, *, header=False):
|
|
60
|
+
path = self.root / relative / name
|
|
61
|
+
try:
|
|
62
|
+
info = path.lstat()
|
|
63
|
+
except FileNotFoundError:
|
|
64
|
+
return False
|
|
65
|
+
if not stat.S_ISREG(info.st_mode):
|
|
66
|
+
return False
|
|
67
|
+
if not header:
|
|
68
|
+
return True
|
|
69
|
+
descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
|
|
70
|
+
try:
|
|
71
|
+
if not stat.S_ISREG(os.fstat(descriptor).st_mode):
|
|
72
|
+
raise OSError(errno.EAGAIN, 'cache marker changed to a non-regular file')
|
|
73
|
+
data = os.read(descriptor, len(TAG))
|
|
74
|
+
self.marker_bytes += len(data)
|
|
75
|
+
return data == TAG
|
|
76
|
+
finally:
|
|
77
|
+
os.close(descriptor)
|
|
78
|
+
|
|
79
|
+
def describe(self, relative):
|
|
80
|
+
if self.protected(relative):
|
|
81
|
+
kind, evidence = 'protected', ['Protected project, configuration or recovery boundary']
|
|
82
|
+
elif self.marker(relative, 'pyvenv.cfg'):
|
|
83
|
+
kind, evidence = 'runtime', ['Regular pyvenv.cfg; environment, not proof of obsolescence or activity']
|
|
84
|
+
elif self.marker(relative, 'CACHEDIR.TAG', header=True):
|
|
85
|
+
if Path(relative).name == 'uv':
|
|
86
|
+
kind, evidence = 'managed_cache', ['Valid CACHEDIR.TAG and name uv; ownership hint, not authentication']
|
|
87
|
+
elif policy._matches_artifact(relative, self.guard_config.artifact_patterns):
|
|
88
|
+
kind, evidence = 'artifact', ['Valid CACHEDIR.TAG and known artifact pattern']
|
|
89
|
+
else:
|
|
90
|
+
kind, evidence = 'cache_hint', ['Valid CACHEDIR.TAG; owner and cleanup protocol unverified']
|
|
91
|
+
elif policy._matches_artifact(relative, self.guard_config.artifact_patterns):
|
|
92
|
+
kind, evidence = 'artifact', ['Known artifact pattern; Git proof and interior inspection pending']
|
|
93
|
+
else:
|
|
94
|
+
return None
|
|
95
|
+
return {'path': relative, 'kind': kind, 'category': 'protected' if kind == 'protected' else 'uncertain',
|
|
96
|
+
'managed_by': 'uv (hint)' if kind == 'managed_cache' else None,
|
|
97
|
+
'evidence': evidence, 'size_bytes': None, 'size_complete': False,
|
|
98
|
+
'interior_checked': False, 'selectable': False}
|
|
99
|
+
|
|
100
|
+
def classify(self, groups):
|
|
101
|
+
candidates = [row['path'] for row in groups if row['kind'] != 'protected']
|
|
102
|
+
tracked, ignored, warning = _git_facts(str(self.root), candidates) if candidates else (set(), set(), None)
|
|
103
|
+
for row in groups:
|
|
104
|
+
path = row['path']
|
|
105
|
+
declared_inside = any(other != path and under(other, path) for other in self.protect)
|
|
106
|
+
tracked_inside = any(under(other, path) for other in tracked)
|
|
107
|
+
row['git_ignored'] = path in ignored
|
|
108
|
+
row['tracked_descendant'] = tracked_inside
|
|
109
|
+
row['declared_protected_descendant'] = declared_inside
|
|
110
|
+
if row['kind'] == 'artifact' and path in ignored and not tracked_inside and not declared_inside and not row.get('protected_roots'):
|
|
111
|
+
row['category'] = 'regenerable'
|
|
112
|
+
row['evidence'].append('Git-ignored with no tracked descendants; read-only hint only')
|
|
113
|
+
return warning, ignored
|
|
114
|
+
|
|
115
|
+
def discover(self, values=(), *, max_depth=4, max_entries=10000, max_directories=256, per_directory=512):
|
|
116
|
+
for value in [max_depth, max_entries, max_directories, per_directory]:
|
|
117
|
+
positive(value)
|
|
118
|
+
scopes = self.scopes(values) if values else ['.']
|
|
119
|
+
queue = [(1, 0, scope) for scope in scopes]
|
|
120
|
+
heapq.heapify(queue)
|
|
121
|
+
groups, deferred, issues, limits = [], [], [], []
|
|
122
|
+
branches = Counter()
|
|
123
|
+
examined = expanded = 0
|
|
124
|
+
while queue:
|
|
125
|
+
_, depth, relative = heapq.heappop(queue)
|
|
126
|
+
try:
|
|
127
|
+
if relative != '.':
|
|
128
|
+
info = (self.root / relative).lstat()
|
|
129
|
+
if stat.S_ISLNK(info.st_mode):
|
|
130
|
+
deferred.append({'path': relative, 'reason': 'LINK_NOT_FOLLOWED'})
|
|
131
|
+
continue
|
|
132
|
+
if not stat.S_ISDIR(info.st_mode):
|
|
133
|
+
issues.append({'path': relative, 'code': 'SOURCE_TYPE_CHANGED'})
|
|
134
|
+
continue
|
|
135
|
+
group = self.describe(relative)
|
|
136
|
+
if group:
|
|
137
|
+
groups.append(group)
|
|
138
|
+
deferred.append({'path': relative, 'reason': group['kind'].upper() + '_NOT_EXPANDED'})
|
|
139
|
+
continue
|
|
140
|
+
else:
|
|
141
|
+
info = self.root.lstat()
|
|
142
|
+
if self.protected('.'):
|
|
143
|
+
groups.append(self.describe('.'))
|
|
144
|
+
deferred.append({'path': '.', 'reason': 'PROTECTED_NOT_EXPANDED'})
|
|
145
|
+
continue
|
|
146
|
+
if depth >= max_depth:
|
|
147
|
+
deferred.append({'path': relative, 'reason': 'DEPTH_FRONTIER'})
|
|
148
|
+
continue
|
|
149
|
+
if expanded >= max_directories or examined >= max_entries:
|
|
150
|
+
limits.append({'path': relative, 'code': 'GLOBAL_DISCOVERY_LIMIT'})
|
|
151
|
+
deferred.extend({'path': name, 'reason': 'GLOBAL_DISCOVERY_LIMIT'} for name in [relative, *(item[2] for item in queue)])
|
|
152
|
+
break
|
|
153
|
+
expanded += 1
|
|
154
|
+
children = []
|
|
155
|
+
with os.scandir(self.root / relative) as entries:
|
|
156
|
+
for index, entry in enumerate(entries):
|
|
157
|
+
if index >= per_directory or examined >= max_entries:
|
|
158
|
+
limits.append({'path': relative, 'code': 'DIRECTORY_ENTRY_LIMIT' if index >= per_directory else 'GLOBAL_ENTRY_LIMIT'})
|
|
159
|
+
deferred.append({'path': relative, 'reason': 'DIRECTORY_REMAINDER_UNOBSERVED'})
|
|
160
|
+
break
|
|
161
|
+
examined += 1
|
|
162
|
+
path = entry.name if relative == '.' else relative + '/' + entry.name
|
|
163
|
+
if self.protected(path):
|
|
164
|
+
groups.append(self.describe(path))
|
|
165
|
+
deferred.append({'path': path, 'reason': 'PROTECTED_NOT_EXPANDED'})
|
|
166
|
+
elif entry.is_symlink():
|
|
167
|
+
deferred.append({'path': path, 'reason': 'LINK_NOT_FOLLOWED'})
|
|
168
|
+
elif entry.is_dir(follow_symlinks=False):
|
|
169
|
+
children.append(path)
|
|
170
|
+
else:
|
|
171
|
+
branches[path.split('/')[0] if '/' in path else '.'] += 1
|
|
172
|
+
if signature((self.root / relative).lstat()) != signature(info):
|
|
173
|
+
issues.append({'path': relative, 'code': 'SOURCE_CHANGED_DURING_SCAN'})
|
|
174
|
+
for path in children:
|
|
175
|
+
# Hints affect scheduling only. Markers, Git facts and
|
|
176
|
+
# protection still determine the read-only group label.
|
|
177
|
+
hinted = (bool(set(path.split('/')) & {'cache', '.cache', 'uv'})
|
|
178
|
+
or policy._matches_artifact(path, self.guard_config.artifact_patterns))
|
|
179
|
+
heapq.heappush(queue, (0 if hinted else 1, depth + 1, path))
|
|
180
|
+
except OSError as error:
|
|
181
|
+
issues.append({'path': relative, 'code': 'OS_ERROR', 'errno': error.errno})
|
|
182
|
+
groups.sort(key=lambda row: row['path'])
|
|
183
|
+
warning, _ = self.classify(groups)
|
|
184
|
+
overview = []
|
|
185
|
+
for kind, label in LABELS.items():
|
|
186
|
+
paths = [row['path'] for row in groups if row['kind'] == kind]
|
|
187
|
+
if paths:
|
|
188
|
+
overview.append({'label': label, 'kind': kind, 'groups': len(paths), 'examples': paths[:3], 'size_bytes': None})
|
|
189
|
+
overview.append({'label': '待复核目录/根文件', 'kind': 'review', 'branches': len(branches), 'observed_files': sum(branches.values()), 'size_bytes': None})
|
|
190
|
+
result = {'schema': 'cleanup_group_discovery/v1', 'workspace': str(self.root), 'operation': 'read_only_discovery',
|
|
191
|
+
'execution_supported': False, 'groups': groups, 'overview': overview,
|
|
192
|
+
'coverage': {'scopes': scopes, 'frontier_depth': max_depth,
|
|
193
|
+
'budgets': {'max_entries': max_entries, 'max_directories': max_directories, 'per_directory': per_directory}, 'frontier_complete': not issues and not limits,
|
|
194
|
+
'workspace_scan_complete': False, 'entries_examined': examined,
|
|
195
|
+
'directories_expanded': expanded, 'unexpanded': deferred, 'limits': limits, 'issues': issues},
|
|
196
|
+
'review_branches': dict(sorted(branches.items())), 'warnings': [warning] if warning else [],
|
|
197
|
+
'marker_bytes_read': self.marker_bytes,
|
|
198
|
+
'notice': 'Read-only directory overview. Unknown sizes are not zero; unexpanded interiors and execution remain unverified.'}
|
|
199
|
+
result['observation_id'] = hashlib.sha256(json.dumps(result, sort_keys=True).encode()).hexdigest()
|
|
200
|
+
return result
|
|
201
|
+
|
|
202
|
+
def scopes(self, values):
|
|
203
|
+
if not values:
|
|
204
|
+
raise ValueError('measure requires at least one explicit scope')
|
|
205
|
+
selected = []
|
|
206
|
+
for value in values:
|
|
207
|
+
absolute = os.path.abspath(self.root / value)
|
|
208
|
+
if absolute == str(self.root) or not classifier.inside_path(absolute, str(self.root)):
|
|
209
|
+
raise ValueError('scope must be below the fixed workspace')
|
|
210
|
+
relative = os.path.relpath(absolute, self.root).replace(os.sep, '/')
|
|
211
|
+
path = self.root
|
|
212
|
+
for component in Path(relative).parts:
|
|
213
|
+
path /= component
|
|
214
|
+
info = path.lstat()
|
|
215
|
+
if stat.S_ISLNK(info.st_mode) or not stat.S_ISDIR(info.st_mode):
|
|
216
|
+
raise ValueError('scope components must be real directories, without aliases')
|
|
217
|
+
if self.protected(relative):
|
|
218
|
+
raise ValueError('protected scope cannot be measured')
|
|
219
|
+
if any(under(relative, other) or under(other, relative) for other in selected):
|
|
220
|
+
raise ValueError('scopes must not overlap')
|
|
221
|
+
selected.append(relative)
|
|
222
|
+
return sorted(selected)
|
|
223
|
+
|
|
224
|
+
def measure(self, values, *, max_entries=20000, max_depth=32):
|
|
225
|
+
positive(max_entries)
|
|
226
|
+
positive(max_depth)
|
|
227
|
+
scopes = self.scopes(values)
|
|
228
|
+
rows, all_inodes = [], {}
|
|
229
|
+
total_examined = 0
|
|
230
|
+
for scope in scopes:
|
|
231
|
+
description = self.describe(scope) or {'path': scope, 'kind': 'review', 'category': 'uncertain', 'managed_by': None, 'evidence': ['No cache or regeneration evidence'], 'selectable': False}
|
|
232
|
+
seen, protected, issues, special = {}, {}, [], []
|
|
233
|
+
digest = hashlib.sha256()
|
|
234
|
+
count = regular = links = directories = 0
|
|
235
|
+
for path in sorted(self.protect):
|
|
236
|
+
if path != scope and under(path, scope):
|
|
237
|
+
protected[path] = 'Declared protected descendant; size unmeasured'
|
|
238
|
+
|
|
239
|
+
def visit(relative, depth):
|
|
240
|
+
nonlocal count, regular, links, directories, total_examined
|
|
241
|
+
if self.protected(relative):
|
|
242
|
+
protected[relative] = 'Protected subtree; not traversed or sized'
|
|
243
|
+
return
|
|
244
|
+
if total_examined >= max_entries:
|
|
245
|
+
issues.append({'path': relative, 'code': 'ENTRY_LIMIT_REACHED'})
|
|
246
|
+
return
|
|
247
|
+
count += 1
|
|
248
|
+
total_examined += 1
|
|
249
|
+
try:
|
|
250
|
+
info = (self.root / relative).lstat()
|
|
251
|
+
if stat.S_ISLNK(info.st_mode):
|
|
252
|
+
spec = classifier.classify_paths(['./' + relative], str(self.root), str(self.root), self.trash)[0]
|
|
253
|
+
if spec.error or spec.indeterminable or spec.wildcard:
|
|
254
|
+
issues.append({'path': relative, 'code': 'LINK_API_UNDETERMINABLE'})
|
|
255
|
+
return
|
|
256
|
+
if not spec.is_symlink:
|
|
257
|
+
issues.append({'path': relative, 'code': 'SOURCE_TYPE_CHANGED'})
|
|
258
|
+
return
|
|
259
|
+
destination = os.path.relpath(spec.link_target, self.root).replace(os.sep, '/')
|
|
260
|
+
if spec.protected or self.protected(destination):
|
|
261
|
+
protected[relative] = 'Protected link boundary; destination not traversed'
|
|
262
|
+
return
|
|
263
|
+
digest.update(json.dumps([relative, signature(info)], separators=(',', ':')).encode() + b'\n')
|
|
264
|
+
if stat.S_ISDIR(info.st_mode):
|
|
265
|
+
directories += 1
|
|
266
|
+
if depth >= max_depth:
|
|
267
|
+
issues.append({'path': relative, 'code': 'DEPTH_LIMIT_REACHED'})
|
|
268
|
+
return
|
|
269
|
+
names = []
|
|
270
|
+
with os.scandir(self.root / relative) as entries:
|
|
271
|
+
for entry in entries:
|
|
272
|
+
if total_examined + len(names) >= max_entries:
|
|
273
|
+
issues.append({'path': relative, 'code': 'ENTRY_LIMIT_REACHED'})
|
|
274
|
+
break
|
|
275
|
+
names.append(entry.name)
|
|
276
|
+
for name in sorted(names):
|
|
277
|
+
if total_examined >= max_entries:
|
|
278
|
+
issues.append({'path': relative + '/' + name, 'code': 'ENTRY_LIMIT_REACHED'})
|
|
279
|
+
break
|
|
280
|
+
visit(relative + '/' + name, depth + 1)
|
|
281
|
+
if signature((self.root / relative).lstat()) != signature(info):
|
|
282
|
+
issues.append({'path': relative, 'code': 'SOURCE_CHANGED_DURING_SCAN'})
|
|
283
|
+
elif stat.S_ISREG(info.st_mode) or stat.S_ISLNK(info.st_mode):
|
|
284
|
+
regular += stat.S_ISREG(info.st_mode)
|
|
285
|
+
links += stat.S_ISLNK(info.st_mode)
|
|
286
|
+
seen[info.st_dev, info.st_ino] = info.st_size
|
|
287
|
+
all_inodes[info.st_dev, info.st_ino] = info.st_size
|
|
288
|
+
else:
|
|
289
|
+
special.append(relative)
|
|
290
|
+
except OSError as error:
|
|
291
|
+
issues.append({'path': relative, 'code': 'OS_ERROR', 'errno': error.errno})
|
|
292
|
+
|
|
293
|
+
visit(scope, 0)
|
|
294
|
+
observed_complete = not issues and not special
|
|
295
|
+
whole_complete = observed_complete and not protected
|
|
296
|
+
description.update(entries_examined=count, regular_files=regular, symlinks=links, directories=directories,
|
|
297
|
+
observed_bytes=sum(seen.values()), size_bytes=sum(seen.values()) if whole_complete else None,
|
|
298
|
+
size_complete=whole_complete, observed_subset_complete=observed_complete,
|
|
299
|
+
protected_roots=protected, issues=issues, special_entries=special,
|
|
300
|
+
metadata_digest=digest.hexdigest(), interior_checked=whole_complete,
|
|
301
|
+
approval='NOT_GRANTED', budget='NOT_CHECKED', core_policy=None)
|
|
302
|
+
rows.append(description)
|
|
303
|
+
warning, ignored = self.classify(rows)
|
|
304
|
+
for row in rows:
|
|
305
|
+
if row['category'] == 'regenerable' and row['size_complete']:
|
|
306
|
+
specs = classifier.classify_paths(['./' + row['path']], str(self.root), str(self.root), self.trash)
|
|
307
|
+
ctx = policy.PolicyContext(workspace=str(self.root), trash_root=self.trash, base_dir=str(self.root), mode=policy.load_mode(self.trash)['mode'], config=self.guard_config)
|
|
308
|
+
def regenerable(batch, context):
|
|
309
|
+
return policy._regenerable(batch, context, lambda workspace, absolute: os.path.relpath(absolute, self.root).replace(os.sep, '/') in ignored)
|
|
310
|
+
verdict = policy._decide_path_batch(specs, ctx, recursive=True, config_loader=lambda workspace: self.config, regenerable_check=regenerable)
|
|
311
|
+
row['core_policy'] = {'decision': verdict.decision, 'code': verdict.code}
|
|
312
|
+
result = {'schema': 'cleanup_group_measurement/v1', 'workspace': str(self.root), 'operation': 'read_only_measurement',
|
|
313
|
+
'execution_supported': False, 'scopes': rows, 'unique_observed_bytes_across_scopes': sum(all_inodes.values()),
|
|
314
|
+
'warnings': [warning] if warning else [], 'marker_bytes_read': self.marker_bytes,
|
|
315
|
+
'entries_examined': total_examined, 'limits': {'max_entries': max_entries, 'max_depth': max_depth},
|
|
316
|
+
'notice': 'Metadata observation only; protected bytes omitted, links not followed, no deletion permission or atomic content snapshot.'}
|
|
317
|
+
result['observation_id'] = hashlib.sha256(json.dumps(result, sort_keys=True).encode()).hexdigest()
|
|
318
|
+
return result
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
def discover_groups(workspace, scopes=(), **limits):
|
|
323
|
+
"""Observe a bounded frontier below the original workspace or exact scopes."""
|
|
324
|
+
return GroupScanner(workspace).discover(scopes, **limits)
|
|
325
|
+
|
|
326
|
+
|
|
327
|
+
def measure_groups(workspace, scopes, **limits):
|
|
328
|
+
"""Measure explicit non-overlapping directories, never following links."""
|
|
329
|
+
return GroupScanner(workspace).measure(scopes, **limits)
|
package/core/policy.py
CHANGED
|
@@ -473,6 +473,11 @@ def regenerable(specs: List[PathSpec], ctx: PolicyContext) -> bool:
|
|
|
473
473
|
and the decision table are untouched. ``spec.resolved`` is still handed
|
|
474
474
|
to git unchanged.
|
|
475
475
|
"""
|
|
476
|
+
return _regenerable(specs, ctx, is_git_ignored)
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
def _regenerable(specs, ctx, git_ignored):
|
|
480
|
+
"""Shared rule; the planner supplies only its scan-local Git facts."""
|
|
476
481
|
if not ctx.config.allow_regenerable:
|
|
477
482
|
return False
|
|
478
483
|
for spec in specs:
|
|
@@ -482,7 +487,7 @@ def regenerable(specs: List[PathSpec], ctx: PolicyContext) -> bool:
|
|
|
482
487
|
_physical(ctx.workspace))
|
|
483
488
|
if not _matches_artifact(rel, ctx.config.artifact_patterns):
|
|
484
489
|
return False
|
|
485
|
-
if not
|
|
490
|
+
if not git_ignored(ctx.workspace, spec.resolved):
|
|
486
491
|
return False
|
|
487
492
|
return True
|
|
488
493
|
|
|
@@ -500,6 +505,18 @@ def _block_undeterminable_effect(spec: OpSpec) -> Verdict:
|
|
|
500
505
|
def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
|
|
501
506
|
recursive: bool) -> Verdict:
|
|
502
507
|
"""One batch of concrete deletion targets through the rule table."""
|
|
508
|
+
return _decide_path_batch(specs, ctx, recursive,
|
|
509
|
+
config_loader=delete_config.load_config,
|
|
510
|
+
regenerable_check=regenerable)
|
|
511
|
+
|
|
512
|
+
|
|
513
|
+
def _decide_path_batch(specs, ctx, recursive, *, config_loader,
|
|
514
|
+
regenerable_check):
|
|
515
|
+
"""Same decision table for live execution and scan-local projection.
|
|
516
|
+
|
|
517
|
+
Actual deletion always enters decide_path_batch and reads fresh facts.
|
|
518
|
+
Planning may reuse facts within its single reviewed metadata snapshot.
|
|
519
|
+
"""
|
|
503
520
|
reasons: List[str] = []
|
|
504
521
|
|
|
505
522
|
errored = [s for s in specs if s.error or s.indeterminable]
|
|
@@ -533,7 +550,7 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
|
|
|
533
550
|
for s in protected_outside[:5]])
|
|
534
551
|
|
|
535
552
|
try:
|
|
536
|
-
deletion_config =
|
|
553
|
+
deletion_config = config_loader(ctx.workspace)
|
|
537
554
|
protection = delete_config.protected_reason(
|
|
538
555
|
[s.resolved for s in specs if s.resolved], ctx.workspace,
|
|
539
556
|
deletion_config)
|
|
@@ -569,7 +586,7 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
|
|
|
569
586
|
["restricted mode permits only explicit single-file "
|
|
570
587
|
"deletes inside the workspace"])
|
|
571
588
|
|
|
572
|
-
if recursive and
|
|
589
|
+
if recursive and regenerable_check(specs, ctx):
|
|
573
590
|
return Verdict(DECISION_ALLOW, CODE_ALLOW_REGENERABLE,
|
|
574
591
|
["all targets are git-ignored and match known "
|
|
575
592
|
"artifact patterns"])
|