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.
Files changed (57) hide show
  1. protocolith/__init__.py +38 -0
  2. protocolith/baseline_groups.py +294 -0
  3. protocolith/baselines.py +288 -0
  4. protocolith/card_svg_render.py +281 -0
  5. protocolith/card_svg_styles.py +178 -0
  6. protocolith/cli.py +796 -0
  7. protocolith/core/__init__.py +63 -0
  8. protocolith/core/_lock_posix.py +29 -0
  9. protocolith/core/_lock_windows.py +29 -0
  10. protocolith/core/atlas.py +406 -0
  11. protocolith/core/atlas_assets/atlas.css +86 -0
  12. protocolith/core/atlas_assets/atlas.html +84 -0
  13. protocolith/core/atlas_assets/atlas.js +370 -0
  14. protocolith/core/atlas_i18n/en.json +61 -0
  15. protocolith/core/canonical.py +124 -0
  16. protocolith/core/capture.py +68 -0
  17. protocolith/core/clock.py +25 -0
  18. protocolith/core/commands.py +356 -0
  19. protocolith/core/errors.py +116 -0
  20. protocolith/core/issue.py +98 -0
  21. protocolith/core/ledger.py +75 -0
  22. protocolith/core/mcp.py +371 -0
  23. protocolith/core/ops.py +183 -0
  24. protocolith/core/rules.py +352 -0
  25. protocolith/core/schema.py +137 -0
  26. protocolith/core/store.py +101 -0
  27. protocolith/core/views.py +136 -0
  28. protocolith/doctor.py +135 -0
  29. protocolith/evidence_card.py +354 -0
  30. protocolith/family_ledger.py +489 -0
  31. protocolith/generic_ohlcv_batch_pre_registration_meta.py +123 -0
  32. protocolith/inspect.py +48 -0
  33. protocolith/nasa_power.py +266 -0
  34. protocolith/nasa_power_fetch.py +64 -0
  35. protocolith/nasa_power_parser.py +133 -0
  36. protocolith/nasa_power_prereg_runner.py +383 -0
  37. protocolith/noaa_coops_fetch.py +188 -0
  38. protocolith/noaa_coops_parser.py +120 -0
  39. protocolith/noaa_coops_prereg_runner.py +341 -0
  40. protocolith/public_ai_protocol.py +176 -0
  41. protocolith/py.typed +0 -0
  42. protocolith/registry.py +139 -0
  43. protocolith/registry_view.py +302 -0
  44. protocolith/rerun_report.py +111 -0
  45. protocolith/run_root.py +243 -0
  46. protocolith/scaffold.py +565 -0
  47. protocolith/source_probe.py +230 -0
  48. protocolith/svg_a11y.py +100 -0
  49. protocolith/tree_overlay.py +343 -0
  50. protocolith/verify_packs.py +251 -0
  51. protocolith/workflows.py +233 -0
  52. protocolith-0.6.0.dist-info/METADATA +283 -0
  53. protocolith-0.6.0.dist-info/RECORD +57 -0
  54. protocolith-0.6.0.dist-info/WHEEL +4 -0
  55. protocolith-0.6.0.dist-info/entry_points.txt +3 -0
  56. protocolith-0.6.0.dist-info/licenses/LICENSE +201 -0
  57. 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())