protocolith 0.6.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.
- protocolith/__init__.py +38 -0
- protocolith/baseline_groups.py +294 -0
- protocolith/baselines.py +288 -0
- protocolith/card_svg_render.py +281 -0
- protocolith/card_svg_styles.py +178 -0
- protocolith/cli.py +796 -0
- protocolith/core/__init__.py +63 -0
- protocolith/core/_lock_posix.py +29 -0
- protocolith/core/_lock_windows.py +29 -0
- protocolith/core/atlas.py +406 -0
- protocolith/core/atlas_assets/atlas.css +86 -0
- protocolith/core/atlas_assets/atlas.html +84 -0
- protocolith/core/atlas_assets/atlas.js +370 -0
- protocolith/core/atlas_i18n/en.json +61 -0
- protocolith/core/canonical.py +124 -0
- protocolith/core/capture.py +68 -0
- protocolith/core/clock.py +25 -0
- protocolith/core/commands.py +356 -0
- protocolith/core/errors.py +116 -0
- protocolith/core/issue.py +98 -0
- protocolith/core/ledger.py +75 -0
- protocolith/core/mcp.py +371 -0
- protocolith/core/ops.py +183 -0
- protocolith/core/rules.py +352 -0
- protocolith/core/schema.py +137 -0
- protocolith/core/store.py +101 -0
- protocolith/core/views.py +136 -0
- protocolith/doctor.py +135 -0
- protocolith/evidence_card.py +354 -0
- protocolith/family_ledger.py +489 -0
- protocolith/generic_ohlcv_batch_pre_registration_meta.py +123 -0
- protocolith/inspect.py +48 -0
- protocolith/nasa_power.py +266 -0
- protocolith/nasa_power_fetch.py +64 -0
- protocolith/nasa_power_parser.py +133 -0
- protocolith/nasa_power_prereg_runner.py +383 -0
- protocolith/noaa_coops_fetch.py +188 -0
- protocolith/noaa_coops_parser.py +120 -0
- protocolith/noaa_coops_prereg_runner.py +341 -0
- protocolith/public_ai_protocol.py +176 -0
- protocolith/py.typed +0 -0
- protocolith/registry.py +139 -0
- protocolith/registry_view.py +302 -0
- protocolith/rerun_report.py +111 -0
- protocolith/run_root.py +243 -0
- protocolith/scaffold.py +565 -0
- protocolith/source_probe.py +230 -0
- protocolith/svg_a11y.py +100 -0
- protocolith/tree_overlay.py +343 -0
- protocolith/verify_packs.py +251 -0
- protocolith/workflows.py +233 -0
- protocolith-0.6.0.dist-info/METADATA +283 -0
- protocolith-0.6.0.dist-info/RECORD +57 -0
- protocolith-0.6.0.dist-info/WHEEL +4 -0
- protocolith-0.6.0.dist-info/entry_points.txt +3 -0
- protocolith-0.6.0.dist-info/licenses/LICENSE +201 -0
- protocolith-0.6.0.dist-info/licenses/NOTICE +13 -0
protocolith/cli.py
ADDED
|
@@ -0,0 +1,796 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Small command-line helpers for Protocolith public workflows."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import argparse
|
|
7
|
+
import json
|
|
8
|
+
import subprocess
|
|
9
|
+
import sys
|
|
10
|
+
from importlib import metadata
|
|
11
|
+
from pathlib import Path
|
|
12
|
+
|
|
13
|
+
from protocolith.core.commands import add_core_commands
|
|
14
|
+
from protocolith.doctor import format_doctor_report, run_doctor
|
|
15
|
+
from protocolith.inspect import (
|
|
16
|
+
format_hash_lines,
|
|
17
|
+
format_json_subset,
|
|
18
|
+
hash_files,
|
|
19
|
+
load_json,
|
|
20
|
+
pick_fields,
|
|
21
|
+
)
|
|
22
|
+
from protocolith.evidence_card import (
|
|
23
|
+
load_evidence_card,
|
|
24
|
+
validate_evidence_card,
|
|
25
|
+
)
|
|
26
|
+
from protocolith.family_ledger import (
|
|
27
|
+
load_frontier_ledger,
|
|
28
|
+
load_family_ledger,
|
|
29
|
+
validate_frontier_ledger,
|
|
30
|
+
validate_family_ledger,
|
|
31
|
+
)
|
|
32
|
+
from protocolith.registry import load_registry, validate_registry
|
|
33
|
+
from protocolith.rerun_report import build_report, load_hash_map
|
|
34
|
+
from protocolith.run_root import (
|
|
35
|
+
RunRootRequest,
|
|
36
|
+
add_deviation,
|
|
37
|
+
list_deviations,
|
|
38
|
+
prepare_run_root,
|
|
39
|
+
record_rights_answer,
|
|
40
|
+
)
|
|
41
|
+
from protocolith.verify_packs import VERIFY_PACKS, run_verify_pack
|
|
42
|
+
from protocolith.scaffold import ScaffoldRequest, build_scaffold
|
|
43
|
+
from protocolith.tree_overlay import (
|
|
44
|
+
load_tree_overlay,
|
|
45
|
+
validate_tree_overlay,
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
REPO_ROOT = Path(__file__).resolve().parents[2]
|
|
50
|
+
DEFAULT_DEMO_ROOT = Path.home() / "protocolith_runs" / "protocolith_demo"
|
|
51
|
+
CLONE_URL = "https://github.com/protocolith/protocolith.git"
|
|
52
|
+
CHECKOUT_COMMANDS = frozenset({"demo", "validate-all", "rerun", "drift", "verify"})
|
|
53
|
+
DEFAULT_CARD_KEYS = (
|
|
54
|
+
"evidence_id",
|
|
55
|
+
"record_type",
|
|
56
|
+
"result_status",
|
|
57
|
+
"reproduction_level",
|
|
58
|
+
"verification_level",
|
|
59
|
+
"protocol_id",
|
|
60
|
+
"official_source_url",
|
|
61
|
+
"access_date",
|
|
62
|
+
"claim_boundary",
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def has_checkout() -> bool:
|
|
67
|
+
"""Return True when running from a repository clone that ships cards and registry."""
|
|
68
|
+
return (REPO_ROOT / "docs" / "evidence_cards").is_dir() and (
|
|
69
|
+
REPO_ROOT / "docs" / "registry" / "evidence_index.json"
|
|
70
|
+
).is_file()
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def package_version() -> str:
|
|
74
|
+
try:
|
|
75
|
+
return metadata.version("protocolith")
|
|
76
|
+
except metadata.PackageNotFoundError:
|
|
77
|
+
return "unknown (not installed as a package)"
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
81
|
+
parser = argparse.ArgumentParser(
|
|
82
|
+
prog="protocolith",
|
|
83
|
+
description="Protocolith helper commands for requests, scaffolds, demos and validation.",
|
|
84
|
+
)
|
|
85
|
+
parser.add_argument(
|
|
86
|
+
"--version",
|
|
87
|
+
action="version",
|
|
88
|
+
version=f"protocolith {package_version()}",
|
|
89
|
+
)
|
|
90
|
+
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
91
|
+
|
|
92
|
+
new_parser = subparsers.add_parser(
|
|
93
|
+
"new",
|
|
94
|
+
aliases=("new-track",),
|
|
95
|
+
description="Create a draft track scaffold. Prompts interactively when run in a terminal.",
|
|
96
|
+
)
|
|
97
|
+
new_parser.add_argument("--source-url")
|
|
98
|
+
new_parser.add_argument("--protocol-id")
|
|
99
|
+
new_parser.add_argument("--domain")
|
|
100
|
+
new_parser.add_argument("--track-type")
|
|
101
|
+
new_parser.add_argument(
|
|
102
|
+
"--execution-mode",
|
|
103
|
+
choices=("MANUAL_NO_AI", "AUTOMATED_AI_ASSISTED"),
|
|
104
|
+
default="MANUAL_NO_AI",
|
|
105
|
+
)
|
|
106
|
+
new_parser.add_argument("--out", type=Path)
|
|
107
|
+
new_parser.add_argument("--source-name", default="Public source under review")
|
|
108
|
+
new_parser.add_argument("--audience", default="public evidence operators")
|
|
109
|
+
new_parser.add_argument(
|
|
110
|
+
"--dry-run",
|
|
111
|
+
action="store_true",
|
|
112
|
+
help="List the files that would be created and write nothing.",
|
|
113
|
+
)
|
|
114
|
+
new_parser.set_defaults(func=_cmd_new)
|
|
115
|
+
|
|
116
|
+
demo_parser = subparsers.add_parser(
|
|
117
|
+
"demo",
|
|
118
|
+
description="Run a small public demo helper.",
|
|
119
|
+
)
|
|
120
|
+
demo_parser.add_argument(
|
|
121
|
+
"name",
|
|
122
|
+
choices=("grok-source-audit", "eea-source-audit", "eea-manual-probe", "validate-all"),
|
|
123
|
+
)
|
|
124
|
+
demo_parser.add_argument("--report", type=Path)
|
|
125
|
+
demo_parser.add_argument(
|
|
126
|
+
"--demo-root",
|
|
127
|
+
type=Path,
|
|
128
|
+
default=DEFAULT_DEMO_ROOT,
|
|
129
|
+
help="Local-only root for demo source clones and reports.",
|
|
130
|
+
)
|
|
131
|
+
demo_parser.add_argument(
|
|
132
|
+
"--grok-repo-dir",
|
|
133
|
+
type=Path,
|
|
134
|
+
help="Existing local clone for xai-org/grok-prompts. Defaults to a local-only demo clone.",
|
|
135
|
+
)
|
|
136
|
+
demo_parser.set_defaults(func=_cmd_demo)
|
|
137
|
+
|
|
138
|
+
validate_parser = subparsers.add_parser(
|
|
139
|
+
"validate-all",
|
|
140
|
+
description="Validate all public evidence cards and the registry.",
|
|
141
|
+
)
|
|
142
|
+
validate_parser.add_argument(
|
|
143
|
+
"--cards-dir",
|
|
144
|
+
type=Path,
|
|
145
|
+
default=REPO_ROOT / "docs" / "evidence_cards",
|
|
146
|
+
)
|
|
147
|
+
validate_parser.add_argument(
|
|
148
|
+
"--registry",
|
|
149
|
+
type=Path,
|
|
150
|
+
default=REPO_ROOT / "docs" / "registry" / "evidence_index.json",
|
|
151
|
+
)
|
|
152
|
+
validate_parser.add_argument(
|
|
153
|
+
"--families-dir",
|
|
154
|
+
type=Path,
|
|
155
|
+
default=REPO_ROOT / "docs" / "track_families",
|
|
156
|
+
help="Directory containing optional *_FAMILY_LEDGER.json files.",
|
|
157
|
+
)
|
|
158
|
+
validate_parser.add_argument(
|
|
159
|
+
"--frontiers-dir",
|
|
160
|
+
type=Path,
|
|
161
|
+
default=REPO_ROOT / "docs" / "track_families",
|
|
162
|
+
help="Directory containing optional *_FRONTIER.json files.",
|
|
163
|
+
)
|
|
164
|
+
validate_parser.add_argument(
|
|
165
|
+
"--trees-dir",
|
|
166
|
+
type=Path,
|
|
167
|
+
default=REPO_ROOT / "docs" / "track_families",
|
|
168
|
+
help="Directory containing optional protocol v3 *_TREE.json files.",
|
|
169
|
+
)
|
|
170
|
+
validate_parser.set_defaults(func=_cmd_validate_all)
|
|
171
|
+
|
|
172
|
+
family_parser = subparsers.add_parser(
|
|
173
|
+
"validate-family",
|
|
174
|
+
description="Validate one R&D family ledger JSON file.",
|
|
175
|
+
)
|
|
176
|
+
family_parser.add_argument("path", type=Path)
|
|
177
|
+
family_parser.set_defaults(func=_cmd_validate_family)
|
|
178
|
+
|
|
179
|
+
frontier_parser = subparsers.add_parser(
|
|
180
|
+
"validate-frontier",
|
|
181
|
+
description="Validate one R&D family frontier JSON file.",
|
|
182
|
+
)
|
|
183
|
+
frontier_parser.add_argument("path", type=Path)
|
|
184
|
+
frontier_parser.add_argument(
|
|
185
|
+
"--base-dir",
|
|
186
|
+
type=Path,
|
|
187
|
+
help="Optional base directory for context capsule and tombstone path checks.",
|
|
188
|
+
)
|
|
189
|
+
frontier_parser.set_defaults(func=_cmd_validate_frontier)
|
|
190
|
+
|
|
191
|
+
tree_parser = subparsers.add_parser(
|
|
192
|
+
"validate-tree",
|
|
193
|
+
description="Validate one protocol v3 R&D tree overlay JSON file.",
|
|
194
|
+
)
|
|
195
|
+
tree_parser.add_argument("path", type=Path)
|
|
196
|
+
tree_parser.set_defaults(func=_cmd_validate_tree)
|
|
197
|
+
|
|
198
|
+
run_root_parser = subparsers.add_parser(
|
|
199
|
+
"run-root",
|
|
200
|
+
description="Create a local-only run root with standard raw/log/hash/report folders.",
|
|
201
|
+
)
|
|
202
|
+
run_root_parser.add_argument("--protocol-id")
|
|
203
|
+
run_root_parser.add_argument("--source-url")
|
|
204
|
+
run_root_parser.add_argument("--operator", default="local operator")
|
|
205
|
+
run_root_parser.add_argument(
|
|
206
|
+
"--root",
|
|
207
|
+
type=Path,
|
|
208
|
+
default=Path.home() / "protocolith_runs",
|
|
209
|
+
help="Local-only parent directory. Defaults to ~/protocolith_runs.",
|
|
210
|
+
)
|
|
211
|
+
run_root_parser.set_defaults(func=_cmd_run_root)
|
|
212
|
+
rr_sub = run_root_parser.add_subparsers(dest="run_root_cmd")
|
|
213
|
+
dev_sub = rr_sub.add_parser("deviation").add_subparsers(dest="dev_cmd", required=True)
|
|
214
|
+
dev_add = dev_sub.add_parser("add")
|
|
215
|
+
dev_add.add_argument("--run-dir", type=Path, required=True)
|
|
216
|
+
for field in ("step", "planned", "happened", "reason", "who"):
|
|
217
|
+
dev_add.add_argument(f"--{field}", required=True)
|
|
218
|
+
dev_add.set_defaults(func=_cmd_deviation_add)
|
|
219
|
+
dev_list = dev_sub.add_parser("list")
|
|
220
|
+
dev_list.add_argument("--run-dir", type=Path, required=True)
|
|
221
|
+
dev_list.set_defaults(func=_cmd_deviation_list)
|
|
222
|
+
rights_sub = rr_sub.add_parser("rights").add_subparsers(dest="rights_cmd", required=True)
|
|
223
|
+
rights_answer = rights_sub.add_parser("answer")
|
|
224
|
+
rights_answer.add_argument("--run-dir", type=Path, required=True)
|
|
225
|
+
for field in ("question-id", "answer", "who"):
|
|
226
|
+
rights_answer.add_argument(f"--{field}", required=True)
|
|
227
|
+
rights_answer.set_defaults(func=_cmd_rights_answer)
|
|
228
|
+
|
|
229
|
+
doctor_parser = subparsers.add_parser(
|
|
230
|
+
"doctor",
|
|
231
|
+
description="Check Python, git and repo layout for cross-platform workflows.",
|
|
232
|
+
)
|
|
233
|
+
doctor_parser.set_defaults(func=_cmd_doctor)
|
|
234
|
+
|
|
235
|
+
inspect_parser = subparsers.add_parser(
|
|
236
|
+
"inspect",
|
|
237
|
+
description="Print selected JSON fields from cards, registry or artifacts.",
|
|
238
|
+
)
|
|
239
|
+
inspect_sub = inspect_parser.add_subparsers(dest="inspect_target", required=True)
|
|
240
|
+
|
|
241
|
+
inspect_card = inspect_sub.add_parser("card", help="Inspect one evidence card JSON file.")
|
|
242
|
+
inspect_card.add_argument("path", type=Path)
|
|
243
|
+
inspect_card.add_argument(
|
|
244
|
+
"--keys",
|
|
245
|
+
nargs="+",
|
|
246
|
+
default=list(DEFAULT_CARD_KEYS),
|
|
247
|
+
help="Top-level JSON keys to print (default: a short card summary).",
|
|
248
|
+
)
|
|
249
|
+
inspect_card.set_defaults(func=_cmd_inspect_card)
|
|
250
|
+
|
|
251
|
+
inspect_registry = inspect_sub.add_parser("registry", help="Inspect the registry index.")
|
|
252
|
+
inspect_registry.add_argument(
|
|
253
|
+
"--registry",
|
|
254
|
+
type=Path,
|
|
255
|
+
default=REPO_ROOT / "docs" / "registry" / "evidence_index.json",
|
|
256
|
+
)
|
|
257
|
+
inspect_registry.add_argument(
|
|
258
|
+
"--keys",
|
|
259
|
+
nargs="+",
|
|
260
|
+
default=["registry_name", "card_count"],
|
|
261
|
+
)
|
|
262
|
+
inspect_registry.set_defaults(func=_cmd_inspect_registry)
|
|
263
|
+
|
|
264
|
+
inspect_json = inspect_sub.add_parser("json", help="Inspect any JSON object file.")
|
|
265
|
+
inspect_json.add_argument("path", type=Path)
|
|
266
|
+
inspect_json.add_argument("--keys", nargs="+", required=True)
|
|
267
|
+
inspect_json.set_defaults(func=_cmd_inspect_json)
|
|
268
|
+
|
|
269
|
+
hash_parser = subparsers.add_parser(
|
|
270
|
+
"hash",
|
|
271
|
+
description="Print SHA-256 hashes for local files.",
|
|
272
|
+
)
|
|
273
|
+
hash_parser.add_argument("paths", nargs="+", type=Path)
|
|
274
|
+
hash_parser.add_argument("--out", type=Path, help="Optional file to write hash lines.")
|
|
275
|
+
hash_parser.set_defaults(func=_cmd_hash)
|
|
276
|
+
|
|
277
|
+
validate_card_parser = subparsers.add_parser(
|
|
278
|
+
"validate-card",
|
|
279
|
+
description="Validate one evidence card JSON file.",
|
|
280
|
+
)
|
|
281
|
+
validate_card_parser.add_argument("path", type=Path)
|
|
282
|
+
validate_card_parser.set_defaults(func=_cmd_validate_card)
|
|
283
|
+
|
|
284
|
+
rerun_parser = subparsers.add_parser(
|
|
285
|
+
"rerun",
|
|
286
|
+
description="Run frozen public-data reruns with cross-platform commands.",
|
|
287
|
+
)
|
|
288
|
+
rerun_sub = rerun_parser.add_subparsers(dest="rerun_name", required=True)
|
|
289
|
+
for name, handler in (
|
|
290
|
+
("nasa-d103", _cmd_rerun_nasa_d103),
|
|
291
|
+
("noaa-d131", _cmd_rerun_noaa_d131),
|
|
292
|
+
):
|
|
293
|
+
sub = rerun_sub.add_parser(name)
|
|
294
|
+
sub.add_argument("--operator", default="local operator")
|
|
295
|
+
sub.add_argument("--root", type=Path, default=Path.home() / "protocolith_runs")
|
|
296
|
+
sub.add_argument("--run-dir", type=Path)
|
|
297
|
+
sub.add_argument("--baseline", type=Path)
|
|
298
|
+
sub.set_defaults(func=handler)
|
|
299
|
+
|
|
300
|
+
rerun_report = rerun_sub.add_parser(
|
|
301
|
+
"report",
|
|
302
|
+
description="Compare original vs rerun hashes; never modifies a card or claim.",
|
|
303
|
+
)
|
|
304
|
+
rerun_report.add_argument("--original", type=Path, required=True)
|
|
305
|
+
rerun_report.add_argument("--rerun", type=Path, required=True)
|
|
306
|
+
rerun_report.add_argument(
|
|
307
|
+
"--outcome", choices=("matches", "differs", "unknown"), default="unknown"
|
|
308
|
+
)
|
|
309
|
+
rerun_report.add_argument("--blocked", action="store_true")
|
|
310
|
+
rerun_report.add_argument("--note", default="")
|
|
311
|
+
rerun_report.add_argument("--out", type=Path)
|
|
312
|
+
rerun_report.set_defaults(func=_cmd_rerun_report)
|
|
313
|
+
|
|
314
|
+
drift_parser = subparsers.add_parser(
|
|
315
|
+
"drift",
|
|
316
|
+
description="Compare fresh public-source probes against frozen baselines.",
|
|
317
|
+
)
|
|
318
|
+
drift_sub = drift_parser.add_subparsers(dest="drift_name", required=True)
|
|
319
|
+
eea_drift = drift_sub.add_parser("eea-source-audit")
|
|
320
|
+
eea_drift.add_argument("--baseline", type=Path)
|
|
321
|
+
eea_drift.add_argument("--report", type=Path)
|
|
322
|
+
eea_drift.set_defaults(func=_cmd_drift_eea)
|
|
323
|
+
|
|
324
|
+
probe_parser = subparsers.add_parser(
|
|
325
|
+
"probe",
|
|
326
|
+
description="SourceProbe v1: metadata-only probe of one public URL (no legal conclusion).",
|
|
327
|
+
)
|
|
328
|
+
probe_parser.add_argument("url")
|
|
329
|
+
probe_parser.add_argument(
|
|
330
|
+
"--marker", action="append", default=[], help="Case-sensitive text to look for."
|
|
331
|
+
)
|
|
332
|
+
probe_parser.add_argument("--out", type=Path, help="Write the JSON probe artifact here.")
|
|
333
|
+
probe_parser.add_argument("--json", action="store_true", help="Print the JSON artifact.")
|
|
334
|
+
probe_parser.set_defaults(func=_cmd_probe)
|
|
335
|
+
|
|
336
|
+
verify_parser = subparsers.add_parser(
|
|
337
|
+
"verify",
|
|
338
|
+
description="Run VERIFY pack checklists with PASS/FAIL output.",
|
|
339
|
+
)
|
|
340
|
+
verify_parser.add_argument(
|
|
341
|
+
"pack",
|
|
342
|
+
choices=sorted(VERIFY_PACKS),
|
|
343
|
+
)
|
|
344
|
+
verify_parser.add_argument(
|
|
345
|
+
"--operator",
|
|
346
|
+
default="verify-operator",
|
|
347
|
+
help="Operator handle for network rerun verify packs.",
|
|
348
|
+
)
|
|
349
|
+
verify_parser.set_defaults(func=_cmd_verify)
|
|
350
|
+
|
|
351
|
+
add_core_commands(subparsers)
|
|
352
|
+
|
|
353
|
+
return parser
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
def main(argv: list[str] | None = None) -> int:
|
|
357
|
+
parser = build_parser()
|
|
358
|
+
args = parser.parse_args(argv)
|
|
359
|
+
if args.command in CHECKOUT_COMMANDS and not has_checkout():
|
|
360
|
+
print(
|
|
361
|
+
f"protocolith {args.command}: this command needs a clone of the repository "
|
|
362
|
+
"(cards, registry and scripts are not part of the pip package).\n"
|
|
363
|
+
f" git clone {CLONE_URL}\n"
|
|
364
|
+
" cd protocolith && uv sync --extra dev\n"
|
|
365
|
+
"For a single card use: protocolith validate-card FILE.json",
|
|
366
|
+
file=sys.stderr,
|
|
367
|
+
)
|
|
368
|
+
return 2
|
|
369
|
+
return int(args.func(args, parser) or 0)
|
|
370
|
+
|
|
371
|
+
|
|
372
|
+
def _cmd_new(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
373
|
+
source_url = _value_or_prompt(args.source_url, "Source URL", parser)
|
|
374
|
+
protocol_id = _value_or_prompt(args.protocol_id, "Protocol ID", parser)
|
|
375
|
+
domain = _value_or_prompt(args.domain, "Domain", parser)
|
|
376
|
+
track_type = _value_or_prompt(args.track_type, "Track type", parser)
|
|
377
|
+
out = args.out or _prompt_path("Output directory", parser)
|
|
378
|
+
|
|
379
|
+
if not out.is_absolute():
|
|
380
|
+
out = _base_dir() / out
|
|
381
|
+
|
|
382
|
+
request = ScaffoldRequest(
|
|
383
|
+
source_url=source_url,
|
|
384
|
+
protocol_id=protocol_id,
|
|
385
|
+
domain=domain,
|
|
386
|
+
track_type=track_type,
|
|
387
|
+
execution_mode=args.execution_mode,
|
|
388
|
+
out_dir=out,
|
|
389
|
+
source_name=args.source_name,
|
|
390
|
+
audience=args.audience,
|
|
391
|
+
)
|
|
392
|
+
try:
|
|
393
|
+
paths = build_scaffold(request, REPO_ROOT, dry_run=args.dry_run)
|
|
394
|
+
except (ValueError, FileExistsError) as exc:
|
|
395
|
+
print(f"protocolith new: {exc}", file=sys.stderr)
|
|
396
|
+
return 2
|
|
397
|
+
if args.dry_run:
|
|
398
|
+
print("dry-run: nothing written; would create:")
|
|
399
|
+
for path in paths:
|
|
400
|
+
print(_display_path(path))
|
|
401
|
+
return 0
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
def _cmd_demo(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
405
|
+
del parser
|
|
406
|
+
if args.name == "validate-all":
|
|
407
|
+
validate_args = argparse.Namespace(
|
|
408
|
+
cards_dir=REPO_ROOT / "docs" / "evidence_cards",
|
|
409
|
+
registry=REPO_ROOT / "docs" / "registry" / "evidence_index.json",
|
|
410
|
+
families_dir=REPO_ROOT / "docs" / "track_families",
|
|
411
|
+
frontiers_dir=REPO_ROOT / "docs" / "track_families",
|
|
412
|
+
trees_dir=REPO_ROOT / "docs" / "track_families",
|
|
413
|
+
)
|
|
414
|
+
return _cmd_validate_all(validate_args, build_parser())
|
|
415
|
+
|
|
416
|
+
if args.name == "eea-source-audit":
|
|
417
|
+
report = args.report or (args.demo_root / "reports" / "source_audit_d001_demo_summary.json")
|
|
418
|
+
return _run_script("protocolith_run_eea_source_audit.py", "--report", str(report))
|
|
419
|
+
|
|
420
|
+
if args.name == "eea-manual-probe":
|
|
421
|
+
report = args.report or (args.demo_root / "reports" / "eea_aq_d001_manual_summary.json")
|
|
422
|
+
return _run_script(
|
|
423
|
+
"protocolith_run_eea_manual_track.py",
|
|
424
|
+
"--probe-eea-api",
|
|
425
|
+
"--report",
|
|
426
|
+
str(report),
|
|
427
|
+
)
|
|
428
|
+
|
|
429
|
+
if args.name == "grok-source-audit":
|
|
430
|
+
repo_dir = args.grok_repo_dir or args.demo_root / "sources" / "grok-prompts"
|
|
431
|
+
_ensure_grok_clone(repo_dir)
|
|
432
|
+
report = args.report or (args.demo_root / "reports" / "grok_prompts_source_audit_d001_demo_summary.json")
|
|
433
|
+
return _run_script(
|
|
434
|
+
"protocolith_run_grok_prompts_source_audit.py",
|
|
435
|
+
"--repo-dir",
|
|
436
|
+
str(repo_dir),
|
|
437
|
+
"--report",
|
|
438
|
+
str(report),
|
|
439
|
+
)
|
|
440
|
+
|
|
441
|
+
raise AssertionError(args.name)
|
|
442
|
+
|
|
443
|
+
|
|
444
|
+
def _cmd_validate_all(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
445
|
+
del parser
|
|
446
|
+
card_paths = sorted(args.cards_dir.glob("*.json"))
|
|
447
|
+
violations: list[str] = []
|
|
448
|
+
|
|
449
|
+
for card_path in card_paths:
|
|
450
|
+
for violation in validate_evidence_card(load_evidence_card(card_path)):
|
|
451
|
+
violations.append(f"{_display_path(card_path)}: {violation}")
|
|
452
|
+
|
|
453
|
+
registry = load_registry(args.registry)
|
|
454
|
+
for violation in validate_registry(registry, REPO_ROOT):
|
|
455
|
+
violations.append(f"{_display_path(args.registry)}: {violation}")
|
|
456
|
+
|
|
457
|
+
family_paths = sorted(args.families_dir.glob("*_FAMILY_LEDGER.json"))
|
|
458
|
+
for family_path in family_paths:
|
|
459
|
+
for violation in validate_family_ledger(load_family_ledger(family_path)):
|
|
460
|
+
violations.append(f"{_display_path(family_path)}: {violation}")
|
|
461
|
+
|
|
462
|
+
frontier_paths = sorted(args.frontiers_dir.glob("*_FRONTIER.json"))
|
|
463
|
+
for frontier_path in frontier_paths:
|
|
464
|
+
for violation in validate_frontier_ledger(
|
|
465
|
+
load_frontier_ledger(frontier_path),
|
|
466
|
+
frontier_path.parent,
|
|
467
|
+
):
|
|
468
|
+
violations.append(f"{_display_path(frontier_path)}: {violation}")
|
|
469
|
+
|
|
470
|
+
tree_paths = sorted(args.trees_dir.glob("*_TREE.json"))
|
|
471
|
+
for tree_path in tree_paths:
|
|
472
|
+
for violation in validate_tree_overlay(load_tree_overlay(tree_path)):
|
|
473
|
+
violations.append(f"{_display_path(tree_path)}: {violation}")
|
|
474
|
+
|
|
475
|
+
if violations:
|
|
476
|
+
for violation in violations:
|
|
477
|
+
print(f"violation: {violation}", file=sys.stderr)
|
|
478
|
+
return 1
|
|
479
|
+
|
|
480
|
+
print(f"valid_cards={len(card_paths)}")
|
|
481
|
+
print(f"valid_registry={_display_path(args.registry)}")
|
|
482
|
+
print(f"valid_family_ledgers={len(family_paths)}")
|
|
483
|
+
print(f"valid_frontier_ledgers={len(frontier_paths)}")
|
|
484
|
+
print(f"valid_tree_overlays={len(tree_paths)}")
|
|
485
|
+
return 0
|
|
486
|
+
|
|
487
|
+
|
|
488
|
+
def _cmd_validate_family(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
489
|
+
del parser
|
|
490
|
+
path = args.path
|
|
491
|
+
if not path.is_absolute():
|
|
492
|
+
path = REPO_ROOT / path
|
|
493
|
+
|
|
494
|
+
violations = validate_family_ledger(load_family_ledger(path))
|
|
495
|
+
if violations:
|
|
496
|
+
for violation in violations:
|
|
497
|
+
print(f"violation: {_display_path(path)}: {violation}", file=sys.stderr)
|
|
498
|
+
return 1
|
|
499
|
+
|
|
500
|
+
print(f"valid_family_ledger={_display_path(path)}")
|
|
501
|
+
return 0
|
|
502
|
+
|
|
503
|
+
|
|
504
|
+
def _cmd_validate_frontier(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
505
|
+
del parser
|
|
506
|
+
path = args.path
|
|
507
|
+
if not path.is_absolute():
|
|
508
|
+
path = REPO_ROOT / path
|
|
509
|
+
base_dir = args.base_dir
|
|
510
|
+
if base_dir is not None and not base_dir.is_absolute():
|
|
511
|
+
base_dir = REPO_ROOT / base_dir
|
|
512
|
+
|
|
513
|
+
violations = validate_frontier_ledger(load_frontier_ledger(path), base_dir or path.parent)
|
|
514
|
+
if violations:
|
|
515
|
+
for violation in violations:
|
|
516
|
+
print(f"violation: {_display_path(path)}: {violation}", file=sys.stderr)
|
|
517
|
+
return 1
|
|
518
|
+
|
|
519
|
+
print(f"valid_frontier_ledger={_display_path(path)}")
|
|
520
|
+
return 0
|
|
521
|
+
|
|
522
|
+
|
|
523
|
+
def _cmd_validate_tree(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
524
|
+
del parser
|
|
525
|
+
path = args.path
|
|
526
|
+
if not path.is_absolute():
|
|
527
|
+
path = REPO_ROOT / path
|
|
528
|
+
|
|
529
|
+
violations = validate_tree_overlay(load_tree_overlay(path))
|
|
530
|
+
if violations:
|
|
531
|
+
for violation in violations:
|
|
532
|
+
print(f"violation: {_display_path(path)}: {violation}", file=sys.stderr)
|
|
533
|
+
return 1
|
|
534
|
+
|
|
535
|
+
print(f"valid_tree_overlay={_display_path(path)}")
|
|
536
|
+
return 0
|
|
537
|
+
|
|
538
|
+
|
|
539
|
+
def _base_dir() -> Path:
|
|
540
|
+
"""Relative paths resolve against the clone in a checkout, otherwise against cwd."""
|
|
541
|
+
return REPO_ROOT if has_checkout() else Path.cwd()
|
|
542
|
+
|
|
543
|
+
|
|
544
|
+
def _resolve_repo_path(path: Path) -> Path:
|
|
545
|
+
return path if path.is_absolute() else _base_dir() / path
|
|
546
|
+
|
|
547
|
+
|
|
548
|
+
def _cmd_inspect_card(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
549
|
+
del parser
|
|
550
|
+
path = _resolve_repo_path(args.path)
|
|
551
|
+
try:
|
|
552
|
+
subset = pick_fields(load_json(path), tuple(args.keys))
|
|
553
|
+
except (OSError, ValueError, KeyError, json.JSONDecodeError) as exc:
|
|
554
|
+
print(f"inspect error: {exc}", file=sys.stderr)
|
|
555
|
+
return 1
|
|
556
|
+
print(format_json_subset(subset), end="")
|
|
557
|
+
return 0
|
|
558
|
+
|
|
559
|
+
|
|
560
|
+
def _cmd_inspect_registry(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
561
|
+
del parser
|
|
562
|
+
path = _resolve_repo_path(args.registry)
|
|
563
|
+
try:
|
|
564
|
+
subset = pick_fields(load_json(path), tuple(args.keys))
|
|
565
|
+
except (OSError, ValueError, KeyError, json.JSONDecodeError) as exc:
|
|
566
|
+
print(f"inspect error: {exc}", file=sys.stderr)
|
|
567
|
+
return 1
|
|
568
|
+
print(format_json_subset(subset), end="")
|
|
569
|
+
return 0
|
|
570
|
+
|
|
571
|
+
|
|
572
|
+
def _cmd_inspect_json(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
573
|
+
return _cmd_inspect_card(args, parser)
|
|
574
|
+
|
|
575
|
+
|
|
576
|
+
def _cmd_hash(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
577
|
+
del parser
|
|
578
|
+
paths = tuple(_resolve_repo_path(path) for path in args.paths)
|
|
579
|
+
try:
|
|
580
|
+
lines = format_hash_lines(hash_files(paths))
|
|
581
|
+
except OSError as exc:
|
|
582
|
+
print(f"hash error: {exc}", file=sys.stderr)
|
|
583
|
+
return 1
|
|
584
|
+
if args.out is not None:
|
|
585
|
+
out_path = _resolve_repo_path(args.out) if not args.out.is_absolute() else args.out
|
|
586
|
+
out_path.parent.mkdir(parents=True, exist_ok=True)
|
|
587
|
+
out_path.write_text(lines, encoding="utf-8")
|
|
588
|
+
print(_display_path(out_path))
|
|
589
|
+
return 0
|
|
590
|
+
print(lines, end="")
|
|
591
|
+
return 0
|
|
592
|
+
|
|
593
|
+
|
|
594
|
+
def _cmd_probe(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
595
|
+
del parser
|
|
596
|
+
from protocolith.source_probe import probe_url
|
|
597
|
+
|
|
598
|
+
try:
|
|
599
|
+
result = probe_url(args.url, args.marker)
|
|
600
|
+
except ValueError as exc:
|
|
601
|
+
print(f"probe error: {exc}", file=sys.stderr)
|
|
602
|
+
return 2
|
|
603
|
+
text = json.dumps(result, indent=2, sort_keys=True) + "\n"
|
|
604
|
+
if args.out is not None:
|
|
605
|
+
args.out.parent.mkdir(parents=True, exist_ok=True)
|
|
606
|
+
args.out.write_text(text, encoding="utf-8")
|
|
607
|
+
if args.json or args.out is None:
|
|
608
|
+
print(text, end="")
|
|
609
|
+
else:
|
|
610
|
+
print(f"{result['recommendation']} http_status={result['http_status']} -> {args.out}")
|
|
611
|
+
return 0
|
|
612
|
+
|
|
613
|
+
|
|
614
|
+
def _cmd_validate_card(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
615
|
+
del parser
|
|
616
|
+
path = _resolve_repo_path(args.path)
|
|
617
|
+
violations = validate_evidence_card(load_evidence_card(path))
|
|
618
|
+
if violations:
|
|
619
|
+
for violation in violations:
|
|
620
|
+
print(f"violation: {_display_path(path)}: {violation}", file=sys.stderr)
|
|
621
|
+
return 1
|
|
622
|
+
print(f"valid_card={_display_path(path)}")
|
|
623
|
+
return 0
|
|
624
|
+
|
|
625
|
+
|
|
626
|
+
def _workflows():
|
|
627
|
+
"""Load the runner workflows lazily so the core CLI works without the optional runner extras."""
|
|
628
|
+
try:
|
|
629
|
+
from protocolith import workflows
|
|
630
|
+
except ModuleNotFoundError as exc:
|
|
631
|
+
raise SystemExit(
|
|
632
|
+
f"This command needs the optional runner dependencies (missing module: {exc.name}); "
|
|
633
|
+
"install them with: pip install 'protocolith[runners]'"
|
|
634
|
+
) from exc
|
|
635
|
+
return workflows
|
|
636
|
+
|
|
637
|
+
|
|
638
|
+
def _cmd_verify(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
639
|
+
del parser
|
|
640
|
+
return run_verify_pack(REPO_ROOT, args.pack, operator=args.operator)
|
|
641
|
+
|
|
642
|
+
|
|
643
|
+
def _cmd_rerun_nasa_d103(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
644
|
+
del parser
|
|
645
|
+
return _workflows().rerun_nasa_d103(
|
|
646
|
+
REPO_ROOT,
|
|
647
|
+
operator=args.operator,
|
|
648
|
+
root=args.root,
|
|
649
|
+
run_dir=args.run_dir,
|
|
650
|
+
baseline_path=args.baseline,
|
|
651
|
+
)
|
|
652
|
+
|
|
653
|
+
|
|
654
|
+
def _cmd_rerun_noaa_d131(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
655
|
+
del parser
|
|
656
|
+
return _workflows().rerun_noaa_d131(
|
|
657
|
+
REPO_ROOT,
|
|
658
|
+
operator=args.operator,
|
|
659
|
+
root=args.root,
|
|
660
|
+
run_dir=args.run_dir,
|
|
661
|
+
baseline_path=args.baseline,
|
|
662
|
+
)
|
|
663
|
+
|
|
664
|
+
|
|
665
|
+
def _cmd_drift_eea(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
666
|
+
del parser
|
|
667
|
+
return _workflows().drift_eea_source_audit(
|
|
668
|
+
REPO_ROOT,
|
|
669
|
+
baseline_path=args.baseline,
|
|
670
|
+
report_path=args.report,
|
|
671
|
+
)
|
|
672
|
+
|
|
673
|
+
|
|
674
|
+
def _cmd_doctor(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
675
|
+
del args, parser
|
|
676
|
+
report = run_doctor(REPO_ROOT)
|
|
677
|
+
print(f"protocolith={package_version()}")
|
|
678
|
+
print(format_doctor_report(report))
|
|
679
|
+
return 0 if report.ok else 1
|
|
680
|
+
|
|
681
|
+
|
|
682
|
+
def _cmd_deviation_add(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
683
|
+
try:
|
|
684
|
+
entry = add_deviation(
|
|
685
|
+
args.run_dir, step=args.step, planned=args.planned,
|
|
686
|
+
happened=args.happened, reason=args.reason, who=args.who,
|
|
687
|
+
)
|
|
688
|
+
except ValueError as exc:
|
|
689
|
+
parser.error(str(exc))
|
|
690
|
+
print(json.dumps(entry, ensure_ascii=False, sort_keys=True))
|
|
691
|
+
return 0
|
|
692
|
+
|
|
693
|
+
|
|
694
|
+
def _cmd_deviation_list(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
695
|
+
try:
|
|
696
|
+
entries = list_deviations(args.run_dir)
|
|
697
|
+
except ValueError as exc:
|
|
698
|
+
parser.error(str(exc))
|
|
699
|
+
for entry in entries:
|
|
700
|
+
print(json.dumps(entry, ensure_ascii=False, sort_keys=True))
|
|
701
|
+
print(f"deviations={len(entries)}")
|
|
702
|
+
return 0
|
|
703
|
+
|
|
704
|
+
|
|
705
|
+
def _cmd_rights_answer(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
706
|
+
try:
|
|
707
|
+
entry = record_rights_answer(args.run_dir, args.question_id, args.answer, args.who)
|
|
708
|
+
except ValueError as exc:
|
|
709
|
+
parser.error(str(exc))
|
|
710
|
+
print(json.dumps(entry, ensure_ascii=False, sort_keys=True))
|
|
711
|
+
return 0
|
|
712
|
+
|
|
713
|
+
|
|
714
|
+
def _cmd_rerun_report(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
715
|
+
outcome = {"matches": True, "differs": False, "unknown": None}[args.outcome]
|
|
716
|
+
try:
|
|
717
|
+
report = build_report(
|
|
718
|
+
load_hash_map(args.original), load_hash_map(args.rerun),
|
|
719
|
+
outcome_matches=outcome, blocked=args.blocked, operator_note=args.note,
|
|
720
|
+
)
|
|
721
|
+
except (ValueError, OSError) as exc:
|
|
722
|
+
parser.error(str(exc))
|
|
723
|
+
text = json.dumps(report, indent=2, sort_keys=True)
|
|
724
|
+
if args.out:
|
|
725
|
+
args.out.write_text(text + "\n", encoding="utf-8")
|
|
726
|
+
print(text)
|
|
727
|
+
return 0
|
|
728
|
+
|
|
729
|
+
|
|
730
|
+
def _cmd_run_root(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
|
|
731
|
+
if not args.protocol_id or not args.source_url:
|
|
732
|
+
parser.error("--protocol-id and --source-url are required to create a run root")
|
|
733
|
+
paths = prepare_run_root(
|
|
734
|
+
RunRootRequest(
|
|
735
|
+
protocol_id=args.protocol_id,
|
|
736
|
+
operator=args.operator,
|
|
737
|
+
source_url=args.source_url,
|
|
738
|
+
root=args.root,
|
|
739
|
+
)
|
|
740
|
+
)
|
|
741
|
+
for path in paths:
|
|
742
|
+
print(path.as_posix())
|
|
743
|
+
return 0
|
|
744
|
+
|
|
745
|
+
|
|
746
|
+
def _value_or_prompt(
|
|
747
|
+
value: str | None, prompt: str, parser: argparse.ArgumentParser
|
|
748
|
+
) -> str:
|
|
749
|
+
if value:
|
|
750
|
+
return value
|
|
751
|
+
if sys.stdin.isatty():
|
|
752
|
+
entered = input(f"{prompt}: ").strip()
|
|
753
|
+
if entered:
|
|
754
|
+
return entered
|
|
755
|
+
parser.error(f"--{prompt.lower().replace(' ', '-')} is required outside interactive mode")
|
|
756
|
+
raise AssertionError("unreachable")
|
|
757
|
+
|
|
758
|
+
|
|
759
|
+
def _prompt_path(prompt: str, parser: argparse.ArgumentParser) -> Path:
|
|
760
|
+
if sys.stdin.isatty():
|
|
761
|
+
entered = input(f"{prompt}: ").strip()
|
|
762
|
+
if entered:
|
|
763
|
+
return Path(entered)
|
|
764
|
+
parser.error("--out is required outside interactive mode")
|
|
765
|
+
raise AssertionError("unreachable")
|
|
766
|
+
|
|
767
|
+
|
|
768
|
+
def _run_script(script_name: str, *args: str) -> int:
|
|
769
|
+
cmd = [sys.executable, str(REPO_ROOT / "scripts" / script_name), *args]
|
|
770
|
+
return subprocess.call(cmd, cwd=REPO_ROOT)
|
|
771
|
+
|
|
772
|
+
|
|
773
|
+
def _display_path(path: Path) -> str:
|
|
774
|
+
try:
|
|
775
|
+
return path.relative_to(REPO_ROOT).as_posix()
|
|
776
|
+
except ValueError:
|
|
777
|
+
return path.as_posix()
|
|
778
|
+
|
|
779
|
+
|
|
780
|
+
def _ensure_grok_clone(repo_dir: Path) -> None:
|
|
781
|
+
if (repo_dir / ".git").is_dir():
|
|
782
|
+
return
|
|
783
|
+
repo_dir.parent.mkdir(parents=True, exist_ok=True)
|
|
784
|
+
subprocess.check_call(
|
|
785
|
+
[
|
|
786
|
+
"git",
|
|
787
|
+
"clone",
|
|
788
|
+
"--depth=1",
|
|
789
|
+
"https://github.com/xai-org/grok-prompts",
|
|
790
|
+
str(repo_dir),
|
|
791
|
+
]
|
|
792
|
+
)
|
|
793
|
+
|
|
794
|
+
|
|
795
|
+
if __name__ == "__main__":
|
|
796
|
+
raise SystemExit(main())
|