@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
|
@@ -1,8 +1,205 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Unreleased changes and maintenance history
|
|
2
|
+
|
|
3
|
+
<a id="current-unreleased-scope"></a>
|
|
4
|
+
|
|
5
|
+
## Current scope: 0.2.9
|
|
6
|
+
|
|
7
|
+
The maintainer selected **0.2.9** for the changes below. Confirm exact-version
|
|
8
|
+
availability through the [release notes](release-notes-0.2.9.md) before installation.
|
|
9
|
+
Cleanup Copilot and its observation tools remain part of **Delete-guard**.
|
|
10
|
+
The separate disclosure-authorization roadmap and commercial work stay paused.
|
|
11
|
+
|
|
12
|
+
| Area | Change | Entry |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| Directory inventory | Bounded overview, explicit-scope discovery and metadata measurement | [CLI workflow](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased) |
|
|
15
|
+
| MCP observations | `cleanup_discover` and `cleanup_measure`; partial data is distinct from a failed call | [Tool contract](../guides/mcp.md#cleanup-observations-unreleased) |
|
|
16
|
+
| Planning performance | Reuse ordinary-file metadata and batch Git facts within one plan | [Planner boundaries](../guides/cleanup-plan.md#review-a-plan) |
|
|
17
|
+
| Corpus regression | Define the normal text corpus by Git-index paths and current working-tree contents | [Contributor workflow](../../CONTRIBUTING.md) |
|
|
18
|
+
|
|
19
|
+
The default executable-plan workflow, original five MCP operations, deletion
|
|
20
|
+
policy, budgets and recovery formats retain their contracts. Overview and
|
|
21
|
+
measurement never grant execution permission. Use doctor and server from the
|
|
22
|
+
same installation; published 0.2.8 has five tools, this checkout has seven.
|
|
23
|
+
See the [latest local validation](#current-validation-checkpoint) before
|
|
24
|
+
interpreting historical counts or host evidence.
|
|
25
|
+
|
|
26
|
+
<a id="cleanup-directory-observations-and-mcp-unreleased"></a>
|
|
27
|
+
|
|
28
|
+
## Cleanup directory observations and MCP (0.2.9)
|
|
29
|
+
|
|
30
|
+
Version 0.2.9 adds shared-Core directory discovery and selected-scope
|
|
31
|
+
measurement, exposed by `agent-guard-cleanup --discover|--measure` and the
|
|
32
|
+
MCP tools `cleanup_discover` / `cleanup_measure`. These additions are absent
|
|
33
|
+
from published 0.2.8. They remain under
|
|
34
|
+
Delete-guard's Cleanup Copilot, with no new production dependency or storage
|
|
35
|
+
migration.
|
|
36
|
+
|
|
37
|
+
Discovery groups runtime/cache hints, prioritizes cache/artifact path hints
|
|
38
|
+
within fixed limits, and records unexpanded areas. Explicit scopes continue
|
|
39
|
+
discovery under the same workspace. Measurement omits protected subtrees and
|
|
40
|
+
keeps unknown whole sizes distinct from observed bytes. All observations
|
|
41
|
+
remain nonselectable and produce no executable plan ID or approval; the
|
|
42
|
+
existing default plan and confirmed safe_delete workflow remain separate.
|
|
43
|
+
|
|
44
|
+
The MCP adapter returns valid partial observations with `ok: true` and
|
|
45
|
+
`partial: true`, preserving the CLI exit code and completeness details. The
|
|
46
|
+
original five tools retain their contracts. The source doctor expects seven
|
|
47
|
+
tools but still invokes only the original three read-only state queries.
|
|
48
|
+
Use doctor and server from the same installation.
|
|
49
|
+
|
|
50
|
+
See [CLI workflow and result fields](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased)
|
|
51
|
+
and [MCP partial-result semantics](../guides/mcp.md#cleanup-observations-unreleased).
|
|
52
|
+
|
|
53
|
+
<a id="cleanup-planning-performance-unreleased"></a>
|
|
54
|
+
|
|
55
|
+
## Cleanup planning performance (0.2.9)
|
|
56
|
+
|
|
57
|
+
Version 0.2.9 reduces repeated ordinary-file path and metadata checks
|
|
58
|
+
and reuses batched Git facts when projecting candidate verdicts. Shared
|
|
59
|
+
decision rules retain their live execution entrypoint; deleting files still
|
|
60
|
+
checks current Git and protection settings. Scan limits, categories, plan
|
|
61
|
+
fingerprints, confirmation and deletion budgets keep their contracts.
|
|
62
|
+
|
|
63
|
+
This performance change is not part of the published 0.2.8 package. On its
|
|
64
|
+
own it changes no recognition rules or MCP tools; the separate observation
|
|
65
|
+
addition above supplies directory groups and read-only MCP entrypoints.
|
|
66
|
+
Neither coordinates application locks. See the [cleanup guide](../guides/cleanup-plan.md)
|
|
67
|
+
for planning and managed-cache boundaries. The earlier validation records
|
|
68
|
+
below retain their original versions and results.
|
|
69
|
+
|
|
70
|
+
<a id="repository-corpus-noise-regression-unreleased"></a>
|
|
71
|
+
|
|
72
|
+
## Repository corpus noise regression (0.2.9)
|
|
73
|
+
|
|
74
|
+
The repository's normal-corpus test now reads current regular UTF-8 files
|
|
75
|
+
named by its own Git index. Tracked modifications and newly staged files are
|
|
76
|
+
included; untracked private adversarial experiments are outside this metric.
|
|
77
|
+
Git failures, a borrowed parent index and unreadable tracked files are not
|
|
78
|
+
silently accepted. Binary files and link targets are outside the text corpus.
|
|
79
|
+
|
|
80
|
+
This corrects the test's collection boundary without changing Exfil rules,
|
|
81
|
+
exemptions or private examples. Regressions check that unsafe tracked and new
|
|
82
|
+
staged content still fails, untracked examples still BLOCK when scanned
|
|
83
|
+
directly, and staging an example brings it into the corpus gate. New files
|
|
84
|
+
must be staged intentionally before this versioned-corpus pre-commit check;
|
|
85
|
+
it is not a whole-workspace safety scan. See the
|
|
86
|
+
[current validation](#current-validation-checkpoint); earlier failed
|
|
87
|
+
checkpoints remain recorded below.
|
|
88
|
+
|
|
89
|
+
## Current validation checkpoint
|
|
90
|
+
|
|
91
|
+
Before the CI corrections below, the versioned 0.2.9 public candidate passed the literal `npm test`: 1197
|
|
92
|
+
Python cases and both Node groups, with no failures, errors or skips.
|
|
93
|
+
All 16 real MCP protocol/doctor/interruption cases executed with the existing
|
|
94
|
+
pinned SDK. The candidate's 227 public source files stayed unchanged during
|
|
95
|
+
the run. This is local candidate validation; remote CI and publication are
|
|
96
|
+
separate checks, available through the [0.2.9 notes](release-notes-0.2.9.md).
|
|
97
|
+
|
|
98
|
+
The first cross-version CI then exposed a test-fixture issue on Python 3.9
|
|
99
|
+
and 3.10: mocking `os.stat` did not inject the intended metadata error through
|
|
100
|
+
those versions' `Path.lstat` implementation. The fixture now injects at
|
|
101
|
+
`Path.lstat` and verifies that the fault was reached, retaining the original
|
|
102
|
+
error/incompleteness assertions. Further macOS logs exposed a preview fast
|
|
103
|
+
path that missed a configured recovery parent through a directory alias.
|
|
104
|
+
It now checks both recovery-path spellings before skipping classification;
|
|
105
|
+
a new alias regression reproduces the pre-fix failure. The HOME fixture uses
|
|
106
|
+
the scanner's physical path, and the read-only fixture disables detached Git
|
|
107
|
+
maintenance before its baseline commit. These corrections retain deletion
|
|
108
|
+
policy and live execution checks. The full run above keeps its original
|
|
109
|
+
checkpoint; subsequent validation uses 1198 public cases and is recorded
|
|
110
|
+
separately.
|
|
111
|
+
|
|
112
|
+
Before the version alignment, local `npm test` passed all 1504 Python cases (1197 in public
|
|
113
|
+
test modules and 307 existing private development cases) and both Node
|
|
114
|
+
groups, with the existing optional MCP SDK enabled. There were no failures,
|
|
115
|
+
errors, skips or automatic retries; the 214 frozen code/configuration inputs
|
|
116
|
+
remained unchanged. Eight new collection-boundary controls and direct scans
|
|
117
|
+
of the original eleven private samples confirm that the detector still BLOCKs
|
|
118
|
+
those samples. Exfil rules and the allowfile were not changed.
|
|
119
|
+
|
|
120
|
+
These are local working-tree results, not acceptance of the versioned
|
|
121
|
+
release or fresh remote CI. The source suite includes private development
|
|
122
|
+
cases absent from a public checkout; public-module and private counts are
|
|
123
|
+
listed separately. The subsequent Markdown consolidation changed no
|
|
124
|
+
production code or tests and did not repeat model trials. Versioned release
|
|
125
|
+
checks are recorded separately in the [0.2.9 notes](release-notes-0.2.9.md#validation).
|
|
126
|
+
|
|
127
|
+
Local checks include actual stdio discovery/measurement against a real
|
|
128
|
+
project and one bounded real Kimi Code inventory task in a synthetic
|
|
129
|
+
workspace (four model requests, three native MCP calls). The latter completed
|
|
130
|
+
scoped discovery and measurement, preserved unknown UV whole size and mixed
|
|
131
|
+
data uncertainty, and left fixture files unchanged. This is one host/task
|
|
132
|
+
sample, not general reliability, application-cache deletion safety or shell
|
|
133
|
+
interception evidence.
|
|
134
|
+
|
|
135
|
+
The overview remains bounded and may leave an incomplete frontier. Finding
|
|
136
|
+
registered roots does not establish a complete workspace scan. The model
|
|
137
|
+
trial's source/task boundaries remain separate from native shell interception
|
|
138
|
+
and application-cache deletion safety.
|
|
139
|
+
|
|
140
|
+
### Earlier source checkpoints
|
|
141
|
+
|
|
142
|
+
At the earlier pre-corpus-fix checkpoint, the full local `npm test` run
|
|
143
|
+
completed 1496 Python cases (1189 in public test modules and 307 existing
|
|
144
|
+
private development cases), with one corpus
|
|
145
|
+
gate failure caused by existing private experiment files. The saved
|
|
146
|
+
pre-change view reproduced the same eleven hits; the then-current public-only
|
|
147
|
+
view passed that single gate. The two Node commands were then run separately
|
|
148
|
+
and passed. That original npm run remains recorded as failed; the public-only
|
|
149
|
+
gate check is not a second full-suite PASS. No Exfil exemption, production rule or
|
|
150
|
+
private fixture was changed to suppress it. The final 25 directory-group
|
|
151
|
+
controls and actual MCP/host checks passed; the earlier targeted run's
|
|
152
|
+
runpy-bootstrap fixture failure was corrected with its log retained.
|
|
153
|
+
|
|
154
|
+
These earlier results retain their failures and scope. They are not the
|
|
155
|
+
latest candidate's outcome; the successful follow-up run is recorded above.
|
|
156
|
+
|
|
157
|
+
<a id="028-development-and-earlier-maintenance-history"></a>
|
|
2
158
|
|
|
3
159
|
<a id="unreleased-changes-and-026-maintenance-history"></a>
|
|
4
160
|
<a id="027-candidate-changes-and-026-maintenance-history"></a>
|
|
5
161
|
|
|
162
|
+
<a id="mcp-diagnosis-and-reliability-maintenance-028-development"></a>
|
|
163
|
+
|
|
164
|
+
## MCP diagnosis and reliability maintenance (0.2.8)
|
|
165
|
+
|
|
166
|
+
The maintainer selected **0.2.8** for an explicit `doctor.py mcp` path,
|
|
167
|
+
real-protocol response-loss checks and documentation. Stable installation
|
|
168
|
+
examples select this exact version; confirm its GitHub release and npm
|
|
169
|
+
availability through the [version notes](release-notes-0.2.8.md). The local
|
|
170
|
+
validation and remote CI checkpoints are recorded separately.
|
|
171
|
+
|
|
172
|
+
The doctor checks a selected Python/optional SDK, service handshake and
|
|
173
|
+
version, the five-tool set, workspace binding and read-only queries. It does
|
|
174
|
+
not call a model, change host configuration or delete/restore files. Its
|
|
175
|
+
version-1 diagnosis and exit codes are separate from the existing
|
|
176
|
+
Kimi/Claude doctor and Decision Protocol surfaces. A direct-service PASS keeps
|
|
177
|
+
host connection, model delivery and interception `UNVERIFIED`.
|
|
178
|
+
|
|
179
|
+
The interruption work covers client deadline, cancellation, stdin EOF and
|
|
180
|
+
service termination after a real deletion has committed but before a reply.
|
|
181
|
+
Checks examine transaction recoverability and persistent budget, without
|
|
182
|
+
assuming that losing a response rolled back the operation. This does not
|
|
183
|
+
prove arbitrary multi-file interruption atomicity. A separate full rerun passed
|
|
184
|
+
1152 Python cases and both Node groups with no failures/errors/skips; local
|
|
185
|
+
157-file package checks passed. The earlier full-run initialization timeout
|
|
186
|
+
and its unresolved cause remain recorded in the
|
|
187
|
+
[0.2.8 notes](release-notes-0.2.8.md#validation-status).
|
|
188
|
+
|
|
189
|
+
The five tools, default deletion policy, recovery format and budget semantics
|
|
190
|
+
retain their contracts. The SDK stays separately optional; the separate
|
|
191
|
+
0.3.0 and commercial plans remain paused. See the
|
|
192
|
+
[MCP diagnosis and interruption guide](../guides/mcp.md#diagnose-a-local-service-028)
|
|
193
|
+
and this release's [bounded compatibility decision](../design/compatibility.md#028-diagnosis-maintenance-decision).
|
|
194
|
+
|
|
195
|
+
The guide also records later Codex 0.165.0 acceptance of the published 0.2.7
|
|
196
|
+
package: three native-client groups and three real-model tasks with 16 MCP
|
|
197
|
+
calls. That exact-version cooperative-MCP evidence is not 0.2.8 acceptance or
|
|
198
|
+
native-shell interception evidence. Earlier checkpoints below keep their
|
|
199
|
+
original versions, results and failure history.
|
|
200
|
+
|
|
201
|
+
## 0.2.7 changes and 0.2.6 maintenance history
|
|
202
|
+
|
|
6
203
|
The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
|
|
7
204
|
optional local MCP tools. Check its exact GitHub release and npm version
|
|
8
205
|
through the [version notes](release-notes-0.2.7.md) before installing; a source
|
package/doctor.py
CHANGED
|
@@ -17,6 +17,8 @@ import sys
|
|
|
17
17
|
import tempfile
|
|
18
18
|
from typing import Any, Optional
|
|
19
19
|
|
|
20
|
+
sys.dont_write_bytecode = True
|
|
21
|
+
|
|
20
22
|
from core.dialects import resolve_dialect
|
|
21
23
|
|
|
22
24
|
|
|
@@ -747,7 +749,7 @@ def check_claude(config_path: Path, run_probe: bool = False) -> list[str]:
|
|
|
747
749
|
return _diagnose("claude", config_path, run_probe).problems
|
|
748
750
|
|
|
749
751
|
|
|
750
|
-
def main(argv: Optional[list[str]] = None) -> int:
|
|
752
|
+
def main(argv: Optional[list[str]] = None, *, _include_mcp=True) -> int:
|
|
751
753
|
parser = argparse.ArgumentParser(description=__doc__)
|
|
752
754
|
subcommands = parser.add_subparsers(dest="harness", required=True)
|
|
753
755
|
kimi = subcommands.add_parser("kimi", help="check the local Kimi hook")
|
|
@@ -756,6 +758,15 @@ def main(argv: Optional[list[str]] = None) -> int:
|
|
|
756
758
|
claude = subcommands.add_parser("claude", help="check a selected Claude settings file")
|
|
757
759
|
claude.add_argument(
|
|
758
760
|
"--config", help="Claude settings.json (defaults to .claude/settings.json in cwd)")
|
|
761
|
+
if _include_mcp:
|
|
762
|
+
mcp = subcommands.add_parser("mcp", help="diagnose an explicit local MCP server (no model call)")
|
|
763
|
+
mcp.add_argument("--python", default=sys.executable,
|
|
764
|
+
help="Python in the optional MCP SDK environment (default: current interpreter)")
|
|
765
|
+
mcp.add_argument("--workspace", required=True, help="existing workspace bound to the server")
|
|
766
|
+
mcp.add_argument("--server", help="trusted server.py path (default: this package's MCP server)")
|
|
767
|
+
mcp.add_argument("--timeout", type=int, default=30, metavar="SECONDS",
|
|
768
|
+
help="total diagnosis deadline, 5..120 seconds (default: 30)")
|
|
769
|
+
mcp.add_argument("--json", action="store_true", help="print the independent MCP diagnosis report")
|
|
759
770
|
for command in (kimi, claude):
|
|
760
771
|
command.add_argument(
|
|
761
772
|
"--probe", action="store_true",
|
|
@@ -791,6 +802,19 @@ def main(argv: Optional[list[str]] = None) -> int:
|
|
|
791
802
|
help="live sentinel timeout, 15..600 seconds (default: 180)",
|
|
792
803
|
)
|
|
793
804
|
args = parser.parse_args(argv)
|
|
805
|
+
if args.harness == "mcp":
|
|
806
|
+
if not args.python or "\0" in args.python:
|
|
807
|
+
parser.error("--python must name a nonempty interpreter")
|
|
808
|
+
if not 5 <= args.timeout <= 120:
|
|
809
|
+
parser.error("--timeout must be from 5 to 120 seconds")
|
|
810
|
+
from adapters.mcp.doctor import diagnose, render
|
|
811
|
+
|
|
812
|
+
report = diagnose(args.python, args.workspace, server=args.server, timeout=args.timeout)
|
|
813
|
+
if args.json:
|
|
814
|
+
print(json.dumps(report, ensure_ascii=False))
|
|
815
|
+
else:
|
|
816
|
+
print(render(report), end="")
|
|
817
|
+
return 0 if report["status"] == "PASS" else 1
|
|
794
818
|
if args.write_baseline is not None and not args.probe:
|
|
795
819
|
parser.error("--write-baseline requires --probe")
|
|
796
820
|
if args.live_sentinel and args.write_baseline is not None:
|
package/live_sentinel.py
CHANGED
|
@@ -332,7 +332,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
|
|
|
332
332
|
arguments = list(sys.argv[1:] if argv is None else argv)
|
|
333
333
|
if "--live-sentinel" not in arguments:
|
|
334
334
|
arguments.append("--live-sentinel")
|
|
335
|
-
return doctor_main(arguments)
|
|
335
|
+
return doctor_main(arguments, _include_mcp=False)
|
|
336
336
|
|
|
337
337
|
|
|
338
338
|
if __name__ == "__main__":
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mokuyoaxis/agent-guard",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.9",
|
|
4
4
|
"description": "Harness-neutral reliability infrastructure for AI coding agents: recoverable destructive actions, disclosure checks, controlled synthetic behaviour experiments, and a shared Core with optional native adapters.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"engines": {
|
|
@@ -51,11 +51,37 @@ Globs passed to `safe_delete` are expanded explicitly before anything moves.
|
|
|
51
51
|
That is why `safe_delete '*.log'` works while `rm *.log` is blocked: the
|
|
52
52
|
guard refuses opaque target sets, not cleanup work.
|
|
53
53
|
|
|
54
|
+
<a id="read-only-cleanup-inventory-unreleased-checkout"></a>
|
|
55
|
+
|
|
56
|
+
## Read-only cleanup inventory (0.2.9)
|
|
57
|
+
|
|
58
|
+
From a 0.2.9 installation or checkout, start a cleanup
|
|
59
|
+
investigation with a bounded directory overview:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --discover --json
|
|
63
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --measure --scope build --json
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Keep the same workspace root when selecting scopes. Use
|
|
67
|
+
`--discover --scope PATH` to inspect an unexpanded directory. Environment and managed-cache
|
|
68
|
+
labels are hints; all groups remain nonselectable. Unknown whole sizes stay
|
|
69
|
+
null, and a complete observed subset is not a complete workspace scan.
|
|
70
|
+
The corresponding MCP tools are `cleanup_discover` and `cleanup_measure`;
|
|
71
|
+
`ok: true, partial: true` is usable partial data, never execution permission.
|
|
72
|
+
|
|
73
|
+
These modes are absent from published 0.2.8. For that package, use its
|
|
74
|
+
existing plan workflow below. With the new modes, produce a separate reviewed
|
|
75
|
+
plan before any execution; `observation_id` cannot replace `plan_id`. Review
|
|
76
|
+
application-managed cache consistency separately. See
|
|
77
|
+
[observation limits](../../docs/guides/cleanup-plan.md#directory-overview-and-measurement-unreleased)
|
|
78
|
+
and [MCP semantics](../../docs/guides/mcp.md#cleanup-observations-unreleased).
|
|
79
|
+
|
|
54
80
|
<a id="cleanup-proposals-027-candidate"></a>
|
|
55
81
|
|
|
56
82
|
## Cleanup proposals (0.2.7)
|
|
57
83
|
|
|
58
|
-
|
|
84
|
+
To propose concrete executable candidates, produce a separate read-only plan:
|
|
59
85
|
|
|
60
86
|
```bash
|
|
61
87
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --json
|
|
@@ -22,6 +22,7 @@ import _bootstrap # noqa: F401
|
|
|
22
22
|
|
|
23
23
|
from core import classifier, recovery
|
|
24
24
|
from core.cleanup import DEFAULT_MAX_DEPTH, DEFAULT_MAX_ENTRIES, plan_cleanup, select_entries
|
|
25
|
+
from core.cleanup_groups import discover_groups, measure_groups
|
|
25
26
|
from core.messages import print_gc_guidance
|
|
26
27
|
|
|
27
28
|
|
|
@@ -29,6 +30,26 @@ LABELS = {"regenerable": "可再生 / regenerable", "discarded": "明确废弃 /
|
|
|
29
30
|
"uncertain": "不确定 / uncertain", "protected": "受保护 / protected"}
|
|
30
31
|
|
|
31
32
|
|
|
33
|
+
def print_groups(result):
|
|
34
|
+
print("Read-only observation; no execution permission. Workspace: "
|
|
35
|
+
+ json.dumps(result["workspace"], ensure_ascii=True))
|
|
36
|
+
if "overview" in result:
|
|
37
|
+
for row in result["overview"]:
|
|
38
|
+
print(row["kind"] + ": " + str(row.get("groups", row.get("branches")))
|
|
39
|
+
+ " groups; size unknown")
|
|
40
|
+
coverage = result["coverage"]
|
|
41
|
+
print("Frontier complete: " + str(coverage["frontier_complete"])
|
|
42
|
+
+ "; workspace scan complete: False; unexpanded: " + str(len(coverage["unexpanded"])))
|
|
43
|
+
print("Use --json for groups, scopes, issues and unexpanded paths; "
|
|
44
|
+
"continue discovery with explicit --scope PATH.")
|
|
45
|
+
else:
|
|
46
|
+
for row in result["scopes"]:
|
|
47
|
+
size = str(row["size_bytes"]) + " B" if row["size_complete"] else (
|
|
48
|
+
"whole size unknown; observed " + str(row["observed_bytes"]) + " B")
|
|
49
|
+
print(json.dumps(row["path"], ensure_ascii=True) + ": " + size)
|
|
50
|
+
print(result["notice"])
|
|
51
|
+
|
|
52
|
+
|
|
32
53
|
def print_plan(plan, *, stream=None, selected=None):
|
|
33
54
|
stream = stream or sys.stdout
|
|
34
55
|
print("Plan: " + plan["plan_id"], file=stream)
|
|
@@ -106,8 +127,13 @@ def main(argv=None):
|
|
|
106
127
|
help="explicitly declare a path/subtree discarded; repeatable")
|
|
107
128
|
parser.add_argument("--protect", action="append", default=[], metavar="PATH",
|
|
108
129
|
help="protect an additional path/subtree; repeatable")
|
|
109
|
-
parser.
|
|
110
|
-
|
|
130
|
+
modes = parser.add_mutually_exclusive_group()
|
|
131
|
+
modes.add_argument("--discover", action="store_true", help="read-only directory overview; no executable plan")
|
|
132
|
+
modes.add_argument("--measure", action="store_true", help="read-only metadata sizes for explicit directory scopes")
|
|
133
|
+
parser.add_argument("--scope", action="append", default=[], metavar="PATH",
|
|
134
|
+
help="directory below the fixed root; repeatable, for --discover or --measure")
|
|
135
|
+
parser.add_argument("--max-entries", type=int, help="entry budget; defaults: plan/discover 10000, measure 20000")
|
|
136
|
+
parser.add_argument("--max-depth", type=int, help="depth budget; defaults: plan 32, discover 4, measure 32")
|
|
111
137
|
parser.add_argument("--json", action="store_true")
|
|
112
138
|
parser.add_argument("--execute", action="store_true")
|
|
113
139
|
parser.add_argument("--plan-id", help="exact ID from the plan being reviewed")
|
|
@@ -115,13 +141,32 @@ def main(argv=None):
|
|
|
115
141
|
help="select an exact selectable plan entry; repeatable")
|
|
116
142
|
args = parser.parse_args(argv)
|
|
117
143
|
try:
|
|
144
|
+
observing = args.discover or args.measure
|
|
145
|
+
if observing and (args.execute or args.plan_id or args.select or args.discard or args.protect):
|
|
146
|
+
raise ValueError("read-only discovery/measurement cannot accept plan declarations or execution arguments")
|
|
147
|
+
if args.scope and not observing:
|
|
148
|
+
raise ValueError("--scope requires --discover or --measure; it does not narrow an executable plan")
|
|
149
|
+
if observing:
|
|
150
|
+
root = args.root or classifier.discover_workspace(os.getcwd())
|
|
151
|
+
limits = {name: value for name, value in (("max_entries", args.max_entries), ("max_depth", args.max_depth))
|
|
152
|
+
if value is not None}
|
|
153
|
+
result = (discover_groups(root, args.scope, **limits) if args.discover
|
|
154
|
+
else measure_groups(root, args.scope, **limits))
|
|
155
|
+
if args.json:
|
|
156
|
+
print(json.dumps(result, ensure_ascii=True, indent=2))
|
|
157
|
+
else:
|
|
158
|
+
print_groups(result)
|
|
159
|
+
complete = (result["coverage"]["frontier_complete"] if args.discover
|
|
160
|
+
else all(row["observed_subset_complete"] for row in result["scopes"]))
|
|
161
|
+
return 0 if complete else 1
|
|
118
162
|
if not args.execute and (args.select or args.plan_id):
|
|
119
163
|
raise ValueError("--select and --plan-id require --execute")
|
|
120
164
|
if args.execute and not args.plan_id:
|
|
121
165
|
raise ValueError("--execute requires the reviewed --plan-id")
|
|
122
166
|
root = args.root or classifier.discover_workspace(os.getcwd())
|
|
123
167
|
options = dict(discard=args.discard, protect=args.protect,
|
|
124
|
-
max_entries=args.max_entries
|
|
168
|
+
max_entries=DEFAULT_MAX_ENTRIES if args.max_entries is None else args.max_entries,
|
|
169
|
+
max_depth=DEFAULT_MAX_DEPTH if args.max_depth is None else args.max_depth)
|
|
125
170
|
plan = plan_cleanup(root, **options)
|
|
126
171
|
if not args.execute:
|
|
127
172
|
if args.json:
|