@rvdbreemen/adr-kit-opencode 0.52.0

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 (129) hide show
  1. package/.claude-plugin/plugin.json +29 -0
  2. package/LICENSE +21 -0
  3. package/README.md +850 -0
  4. package/bin/adr +1552 -0
  5. package/bin/adr-audit +454 -0
  6. package/bin/adr-context +584 -0
  7. package/bin/adr-discover +546 -0
  8. package/bin/adr-doctor +166 -0
  9. package/bin/adr-generate-scripts +421 -0
  10. package/bin/adr-grill-signal +131 -0
  11. package/bin/adr-guardian +1263 -0
  12. package/bin/adr-index +199 -0
  13. package/bin/adr-judge +2832 -0
  14. package/bin/adr-judge-precommit +87 -0
  15. package/bin/adr-lint +2087 -0
  16. package/bin/adr-mcp +1093 -0
  17. package/bin/adr-migrate +644 -0
  18. package/bin/adr-quality +275 -0
  19. package/bin/adr-readiness +211 -0
  20. package/bin/adr-readiness-ci +111 -0
  21. package/bin/adr-related +401 -0
  22. package/bin/adr-renumber +254 -0
  23. package/bin/adr-retire +467 -0
  24. package/bin/adr-settings +399 -0
  25. package/bin/adr-status +797 -0
  26. package/bin/adr-suggest +803 -0
  27. package/bin/adr-watch +674 -0
  28. package/bin/adr_catalog.py +536 -0
  29. package/bin/adr_config.py +280 -0
  30. package/bin/adr_doctor_checks.py +407 -0
  31. package/bin/adr_doctor_core.py +342 -0
  32. package/bin/adr_doctor_models.py +186 -0
  33. package/bin/adr_doctor_probes.py +216 -0
  34. package/bin/adr_format.py +786 -0
  35. package/bin/adr_grill_signal.py +123 -0
  36. package/bin/adr_guardian_queue.py +218 -0
  37. package/bin/adr_history_scan.py +278 -0
  38. package/bin/adr_index_core.py +443 -0
  39. package/bin/adr_llm.py +333 -0
  40. package/bin/adr_llm_judge_migration.py +314 -0
  41. package/bin/adr_quality_core.py +674 -0
  42. package/bin/adr_query.py +678 -0
  43. package/bin/adr_readiness.py +442 -0
  44. package/bin/adr_readiness_ci.py +123 -0
  45. package/bin/adr_regex.py +165 -0
  46. package/bin/adr_regex_worker.py +30 -0
  47. package/bin/adr_retrieval_health.py +385 -0
  48. package/bin/adr_schema.py +448 -0
  49. package/bin/adr_state.py +172 -0
  50. package/bin/bump-version +71 -0
  51. package/clients/workflows.json +229 -0
  52. package/hooks/__init__.py +1 -0
  53. package/hooks/adapters/__init__.py +13 -0
  54. package/hooks/adapters/claude.py +27 -0
  55. package/hooks/adapters/codex.py +26 -0
  56. package/hooks/adapters/copilot.py +11 -0
  57. package/hooks/adr-hook.py +128 -0
  58. package/hooks/adr_hook_core.py +843 -0
  59. package/hooks/adr_pr_guard.py +367 -0
  60. package/instructions/ADR-guide.md +48 -0
  61. package/instructions/adr.coding.md +82 -0
  62. package/instructions/adr.review.md +182 -0
  63. package/opencode/plugin.ts +451 -0
  64. package/package.json +41 -0
  65. package/schemas/adr-context-probes.schema.json +56 -0
  66. package/schemas/adr-enforcement.schema.json +57 -0
  67. package/schemas/adr-frontmatter.schema.json +144 -0
  68. package/schemas/adr-index.schema.json +276 -0
  69. package/schemas/adr-kit-config.schema.json +371 -0
  70. package/schemas/adr-readiness.schema.json +41 -0
  71. package/schemas/client-capabilities.schema.json +503 -0
  72. package/schemas/client-certification.schema.json +101 -0
  73. package/schemas/doctor-output.schema.json +92 -0
  74. package/schemas/marketplace.json.schema.json +70 -0
  75. package/schemas/plugin.json.schema.json +67 -0
  76. package/scripts/adr_settings.py +239 -0
  77. package/scripts/benchmark-adr-grilling.py +323 -0
  78. package/scripts/benchmark-client-generation.py +178 -0
  79. package/scripts/build-client-adapters.py +139 -0
  80. package/scripts/bump-version.py +304 -0
  81. package/scripts/check-branch-sync.py +243 -0
  82. package/scripts/check-release-version.py +81 -0
  83. package/scripts/client_certification.py +153 -0
  84. package/scripts/client_evidence.py +280 -0
  85. package/scripts/client_generation.py +288 -0
  86. package/scripts/client_generation_artifacts.py +351 -0
  87. package/scripts/client_generation_model.py +173 -0
  88. package/scripts/client_generation_state.py +260 -0
  89. package/scripts/client_support_matrix.py +360 -0
  90. package/scripts/install-agent-envs.py +300 -0
  91. package/scripts/probe-client-events.py +183 -0
  92. package/scripts/project_setup.py +379 -0
  93. package/scripts/refresh-otgw-corpus.py +219 -0
  94. package/scripts/settings.py +81 -0
  95. package/scripts/setup-project.py +205 -0
  96. package/scripts/sync-agent-plugins.py +17 -0
  97. package/scripts/version_sites.py +377 -0
  98. package/skills/adr/SKILL.md +780 -0
  99. package/skills/audit/SKILL.md +103 -0
  100. package/skills/context/SKILL.md +77 -0
  101. package/skills/grill/SKILL.md +84 -0
  102. package/skills/grill/agents/openai.yaml +4 -0
  103. package/skills/guardian/SKILL.md +316 -0
  104. package/skills/init/SKILL.md +499 -0
  105. package/skills/install-hooks/SKILL.md +154 -0
  106. package/skills/judge/SKILL.md +168 -0
  107. package/skills/lint/SKILL.md +321 -0
  108. package/skills/migrate/SKILL.md +313 -0
  109. package/skills/related/SKILL.md +62 -0
  110. package/skills/retire/SKILL.md +41 -0
  111. package/skills/review/SKILL.md +167 -0
  112. package/skills/settings/SKILL.md +73 -0
  113. package/skills/setup/SKILL.md +128 -0
  114. package/skills/supersede/SKILL.md +136 -0
  115. package/skills/upgrade/SKILL.md +273 -0
  116. package/templates/adr-kit-guide.md +354 -0
  117. package/templates/adr-template.canonical.md +115 -0
  118. package/templates/adr-template.madr.md +131 -0
  119. package/templates/adr-template.md +131 -0
  120. package/templates/adr-template.nygard.md +111 -0
  121. package/templates/cc-settings/guardian-hook-entry.json +9 -0
  122. package/templates/githooks/pre-commit +337 -0
  123. package/templates/github-workflows/adr-audit.yml +58 -0
  124. package/templates/github-workflows/adr-guardian-audit.yml +133 -0
  125. package/templates/github-workflows/adr-index-check.yml +30 -0
  126. package/templates/github-workflows/adr-judge.yml +31 -0
  127. package/templates/github-workflows/adr-readiness.yml +18 -0
  128. package/templates/validate_adr_template.py +38 -0
  129. package/templates/validate_adr_template.sh +74 -0
@@ -0,0 +1,377 @@
1
+ #!/usr/bin/env python3
2
+ """Read, validate and write the release version across every declared site.
3
+
4
+ `packaging/version-sites.json` is the single registry of where the version lives.
5
+ The bump writer, the release gate, the client-adapter generator and the tests all
6
+ go through this module, so a new version-bearing file is declared once instead of
7
+ being taught to three separate code paths that can drift apart.
8
+
9
+ Every function reports ALL findings rather than aborting on the first one: a
10
+ version bump should surface its complete work list in one pass.
11
+ """
12
+ from __future__ import annotations
13
+
14
+ import json
15
+ import os
16
+ import re
17
+ import tempfile
18
+ from dataclasses import dataclass
19
+ from pathlib import Path
20
+ from typing import Iterable
21
+
22
+ REGISTRY_RELPATH = "packaging/version-sites.json"
23
+ SEMVER = re.compile(r"^\d+\.\d+\.\d+$")
24
+
25
+ #: Every `kind` this module can read and write. A registry entry declaring
26
+ #: anything else is a hard error at both ends: verified-but-never-written is the
27
+ #: exact failure mode ADR-013 exists to prevent.
28
+ SITE_KINDS = frozenset({"json", "regex", "regex_all"})
29
+
30
+
31
+ class VersionSiteError(RuntimeError):
32
+ """Raised when the registry itself is unusable (missing file, bad shape)."""
33
+
34
+
35
+ @dataclass(frozen=True)
36
+ class Finding:
37
+ label: str
38
+ path: str
39
+ found: str | None
40
+ expected: str
41
+
42
+ def __str__(self) -> str:
43
+ found = "missing" if self.found is None else repr(self.found)
44
+ return f"{self.label} ({self.path}) = {found}, expected {self.expected!r}"
45
+
46
+
47
+ def load_registry(root: Path) -> dict:
48
+ path = root / REGISTRY_RELPATH
49
+ if not path.is_file():
50
+ raise VersionSiteError(f"version-site registry not found: {REGISTRY_RELPATH}")
51
+ try:
52
+ registry = json.loads(path.read_text(encoding="utf-8"))
53
+ except json.JSONDecodeError as exc:
54
+ raise VersionSiteError(f"invalid JSON in {REGISTRY_RELPATH}: {exc}") from exc
55
+ for key in ("canonical", "sites"):
56
+ if key not in registry:
57
+ raise VersionSiteError(f"{REGISTRY_RELPATH} is missing '{key}'")
58
+ return registry
59
+
60
+
61
+ # --- JSON pointer (RFC 6901), only the subset the registry needs ---------------
62
+
63
+ def _pointer_parts(pointer: str) -> list[str]:
64
+ if not pointer.startswith("/"):
65
+ raise VersionSiteError(f"JSON pointer must start with '/': {pointer!r}")
66
+ return [p.replace("~1", "/").replace("~0", "~") for p in pointer[1:].split("/")]
67
+
68
+
69
+ def _pointer_get(doc: object, pointer: str) -> object | None:
70
+ node = doc
71
+ for part in _pointer_parts(pointer):
72
+ if isinstance(node, list):
73
+ if not part.isdigit() or int(part) >= len(node):
74
+ return None
75
+ node = node[int(part)]
76
+ elif isinstance(node, dict):
77
+ if part not in node:
78
+ return None
79
+ node = node[part]
80
+ else:
81
+ return None
82
+ return node
83
+
84
+
85
+ def _pointer_set(doc: object, pointer: str, value: str) -> bool:
86
+ parts = _pointer_parts(pointer)
87
+ node = doc
88
+ for part in parts[:-1]:
89
+ if isinstance(node, list):
90
+ if not part.isdigit() or int(part) >= len(node):
91
+ return False
92
+ node = node[int(part)]
93
+ elif isinstance(node, dict):
94
+ if part not in node:
95
+ return False
96
+ node = node[part]
97
+ else:
98
+ return False
99
+ last = parts[-1]
100
+ if isinstance(node, list):
101
+ if not last.isdigit() or int(last) >= len(node):
102
+ return False
103
+ node[int(last)] = value
104
+ elif isinstance(node, dict):
105
+ if last not in node:
106
+ return False
107
+ node[last] = value
108
+ else:
109
+ return False
110
+ return True
111
+
112
+
113
+ # --- reading ------------------------------------------------------------------
114
+
115
+ def read_canonical(root: Path, registry: dict | None = None) -> str | None:
116
+ """Return the version from the canonical source (the CHANGELOG heading)."""
117
+ registry = registry or load_registry(root)
118
+ canonical = registry["canonical"]
119
+ path = root / canonical["path"]
120
+ if not path.is_file():
121
+ return None
122
+ pattern = re.compile(canonical["pattern"], re.MULTILINE)
123
+ match = pattern.search(path.read_text(encoding="utf-8"))
124
+ return match.group(1) if match else None
125
+
126
+
127
+ def _read_site(root: Path, site: dict) -> list[str | None]:
128
+ """Return every version value the site currently carries (may be several)."""
129
+ path = root / site["path"]
130
+ if not path.is_file():
131
+ return [None]
132
+ kind = site["kind"]
133
+ if kind == "json":
134
+ try:
135
+ doc = json.loads(path.read_text(encoding="utf-8"))
136
+ except json.JSONDecodeError:
137
+ return [None]
138
+ value = _pointer_get(doc, site["pointer"])
139
+ return [value if isinstance(value, str) else None]
140
+ if kind in {"regex", "regex_all"}:
141
+ matches = re.findall(site["pattern"], path.read_text(encoding="utf-8"))
142
+ if not matches:
143
+ return [None]
144
+ # Each match is a tuple of capture groups; group 2 is the version.
145
+ values = [m[1] if isinstance(m, tuple) else m for m in matches]
146
+ return values if kind == "regex_all" else values[:1]
147
+ raise VersionSiteError(_unknown_kind_message(kind, site["path"]))
148
+
149
+
150
+ def read_all(root: Path, registry: dict | None = None) -> list[tuple[dict, list[str | None]]]:
151
+ registry = registry or load_registry(root)
152
+ return [(site, _read_site(root, site)) for site in registry["sites"]]
153
+
154
+
155
+ # --- validating ---------------------------------------------------------------
156
+
157
+ def check(root: Path, expected: str, registry: dict | None = None) -> list[Finding]:
158
+ """Return EVERY mismatch, never aborting on the first one."""
159
+ registry = registry or load_registry(root)
160
+ findings: list[Finding] = []
161
+
162
+ canonical = read_canonical(root, registry)
163
+ if canonical != expected:
164
+ findings.append(
165
+ Finding(registry["canonical"]["label"], registry["canonical"]["path"], canonical, expected)
166
+ )
167
+
168
+ for site, values in read_all(root, registry):
169
+ for value in values:
170
+ if value != expected:
171
+ findings.append(Finding(site["label"], site["path"], value, expected))
172
+
173
+ for rule in registry.get("must_not_carry_version", []):
174
+ path = root / rule["path"]
175
+ if not path.is_file():
176
+ continue
177
+ try:
178
+ doc = json.loads(path.read_text(encoding="utf-8"))
179
+ except json.JSONDecodeError:
180
+ continue
181
+ value = _pointer_get(doc, rule["pointer"])
182
+ if value is not None:
183
+ findings.append(
184
+ Finding(f"{rule['label']} must not carry a version", rule["path"], str(value), "absent")
185
+ )
186
+ return findings
187
+
188
+
189
+ # --- writing ------------------------------------------------------------------
190
+
191
+ def _unknown_kind_message(kind: object, path: str) -> str:
192
+ return (
193
+ f"unknown site kind {kind!r} for {path}; this module implements "
194
+ f"{sorted(SITE_KINDS)}. A kind nothing writes would leave the site "
195
+ "verified but never bumped, which is the drift ADR-013 exists to stop."
196
+ )
197
+
198
+
199
+ def _rewrite(site: dict, text: str, version: str) -> str:
200
+ """Return `text` with the version substituted. Pure: touches no file."""
201
+ kind = site["kind"]
202
+
203
+ if kind == "json":
204
+ try:
205
+ doc = json.loads(text)
206
+ except json.JSONDecodeError as exc:
207
+ raise VersionSiteError(f"invalid JSON in {site['path']}: {exc}") from exc
208
+ if not _pointer_set(doc, site["pointer"], version):
209
+ raise VersionSiteError(f"pointer {site['pointer']} not found in {site['path']}")
210
+ return json.dumps(doc, indent=2, ensure_ascii=False) + "\n"
211
+
212
+ if kind in {"regex", "regex_all"}:
213
+ pattern = re.compile(site["pattern"])
214
+ if not pattern.search(text):
215
+ raise VersionSiteError(
216
+ f"pattern for {site['label']} did not match anything in {site['path']}"
217
+ )
218
+ count = 0 if kind == "regex_all" else 1
219
+ return pattern.sub(
220
+ lambda m: f"{m.group(1)}{version}{m.group(3) if m.lastindex and m.lastindex >= 3 else ''}",
221
+ text,
222
+ count=count,
223
+ )
224
+
225
+ raise VersionSiteError(_unknown_kind_message(kind, site["path"]))
226
+
227
+
228
+ def plan_writes(
229
+ root: Path,
230
+ version: str,
231
+ registry: dict | None = None,
232
+ overrides: dict[Path, str] | None = None,
233
+ ) -> dict[Path, bytes]:
234
+ """Compute the post-image of every declared site without touching the disk.
235
+
236
+ `overrides` seeds a file's pre-image with text the caller has already
237
+ computed, instead of reading it from disk. The bump writer needs this for
238
+ CHANGELOG.md: it inserts the release heading and rewrites the compare-link
239
+ block, and the registry *also* declares the `[Unreleased]` link line as a
240
+ site. Without a shared pre-image the two are computed from the same stale
241
+ bytes and the caller has to pick one, which is how the link block came to be
242
+ written by a tool the runbook does not name (TASK-139). One image, folded in
243
+ order, is the only version of this that cannot silently drop half the edit.
244
+
245
+ Planning the whole registry before the first byte is written is what makes an
246
+ undeclarable site loud instead of silent: a `kind` this module does not
247
+ implement, a pattern that matches nothing or a pointer that does not resolve
248
+ aborts the entire bump, rather than being skipped or leaving the sites ahead
249
+ of it written and the rest stale.
250
+
251
+ Every planning failure is collected and reported together, because a release
252
+ should surface its complete work list in one pass (ADR-013) instead of one
253
+ error per run.
254
+
255
+ Sites are folded into a shared working image in registry order, because two
256
+ sites may declare the same path -- README.md carries both version pins -- and
257
+ the second substitution must see the first one's edit rather than the stale
258
+ bytes on disk.
259
+
260
+ Returns only the paths whose content actually changes.
261
+ """
262
+ registry = registry or load_registry(root)
263
+ originals: dict[Path, str] = {}
264
+ working: dict[Path, str] = {}
265
+ missing: set[Path] = set()
266
+ errors: list[str] = []
267
+
268
+ # An override still compares against the bytes on disk, so a file the caller
269
+ # rewrote is reported as changed even when no declared site matched in it.
270
+ for path, text in (overrides or {}).items():
271
+ originals[path] = path.read_text(encoding="utf-8") if path.is_file() else ""
272
+ working[path] = text
273
+
274
+ for site in registry["sites"]:
275
+ path = root / site["path"]
276
+ if path in missing:
277
+ continue
278
+ if path not in originals:
279
+ if not path.is_file():
280
+ missing.add(path)
281
+ errors.append(f"declared version site is missing: {site['path']}")
282
+ continue
283
+ originals[path] = path.read_text(encoding="utf-8")
284
+ working[path] = originals[path]
285
+ try:
286
+ working[path] = _rewrite(site, working[path], version)
287
+ except VersionSiteError as exc:
288
+ errors.append(str(exc))
289
+
290
+ if errors:
291
+ raise VersionSiteError(
292
+ "cannot write the version to every declared site:\n"
293
+ + "\n".join(f" - {message}" for message in errors)
294
+ )
295
+ return {
296
+ path: text.encode("utf-8")
297
+ for path, text in working.items()
298
+ if text != originals[path]
299
+ }
300
+
301
+
302
+ def _atomic_write_bytes(path: Path, content: bytes) -> None:
303
+ """Replace `path` in one step, so no reader ever sees a half-written file."""
304
+ temp_path = None
305
+ try:
306
+ with tempfile.NamedTemporaryFile(
307
+ mode="wb",
308
+ dir=path.parent,
309
+ prefix=f".{path.name}.",
310
+ suffix=".tmp",
311
+ delete=False,
312
+ ) as handle:
313
+ handle.write(content)
314
+ handle.flush()
315
+ os.fsync(handle.fileno())
316
+ temp_path = Path(handle.name)
317
+ os.replace(temp_path, path)
318
+ temp_path = None
319
+ finally:
320
+ if temp_path is not None:
321
+ temp_path.unlink(missing_ok=True)
322
+
323
+
324
+ def apply_transaction(changes: dict[Path, bytes]) -> None:
325
+ """Write every planned change, restoring all of them if any write fails.
326
+
327
+ A release tool that leaves half the manifests bumped is worse than one that
328
+ misses a file: the tree then carries two versions and no tool can tell which
329
+ is intended. Only the paths already written are restored -- `_atomic_write_bytes`
330
+ replaces in one step, so a failed write left its target untouched, and
331
+ rewriting it could only invent a second failure.
332
+ """
333
+ originals = {path: path.read_bytes() for path in changes}
334
+ written: list[Path] = []
335
+ try:
336
+ for path, content in changes.items():
337
+ _atomic_write_bytes(path, content)
338
+ written.append(path)
339
+ except BaseException as exc:
340
+ rollback_errors = []
341
+ for path in written:
342
+ try:
343
+ _atomic_write_bytes(path, originals[path])
344
+ except BaseException as rollback_exc: # pragma: no cover - catastrophic
345
+ rollback_errors.append(f"{path}: {rollback_exc}")
346
+ if rollback_errors:
347
+ raise VersionSiteError(
348
+ f"release write failed ({exc}); rollback also failed: "
349
+ + "; ".join(rollback_errors)
350
+ ) from exc
351
+ raise VersionSiteError(
352
+ f"release write failed; all targets were rolled back: {exc}"
353
+ ) from exc
354
+
355
+
356
+ def describe_changes(root: Path, changes: dict, registry: dict | None = None) -> list[str]:
357
+ """Render a planned change set as `path (label, label)` lines, in registry order."""
358
+ registry = registry or load_registry(root)
359
+ labels: dict[str, list[str]] = {}
360
+ for site in registry["sites"]:
361
+ if (root / site["path"]) in changes:
362
+ labels.setdefault(site["path"], []).append(site["label"])
363
+ return [f"{path} ({', '.join(names)})" for path, names in labels.items()]
364
+
365
+
366
+ def write_all(root: Path, version: str, registry: dict | None = None) -> list[str]:
367
+ """Write the version to every declared site. Returns the changed paths."""
368
+ if not SEMVER.match(version):
369
+ raise VersionSiteError(f"not a MAJOR.MINOR.PATCH version: {version!r}")
370
+ registry = registry or load_registry(root)
371
+ changes = plan_writes(root, version, registry)
372
+ apply_transaction(changes)
373
+ return describe_changes(root, changes, registry)
374
+
375
+
376
+ def format_findings(findings: Iterable[Finding]) -> str:
377
+ return "\n".join(f" - {f}" for f in findings)