@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,173 @@
1
+ """Shared model and bounded I/O primitives for client generation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ import re
8
+ import threading
9
+ from dataclasses import dataclass
10
+ from pathlib import Path
11
+
12
+ CLIENT_IDS = ("claude-code-cli", "codex-cli", "github-copilot-cli")
13
+ WORKFLOW_IDS = (
14
+ "adr",
15
+ "audit",
16
+ "context",
17
+ "grill",
18
+ "guardian",
19
+ "init",
20
+ "install-hooks",
21
+ "judge",
22
+ "lint",
23
+ "migrate",
24
+ "related",
25
+ "retire",
26
+ "review",
27
+ "settings",
28
+ "setup",
29
+ "supersede",
30
+ "upgrade",
31
+ )
32
+ GENERATED_CLIENTS = {"codex-cli": "codex", "github-copilot-cli": "copilot"}
33
+ COPY_ROOTS = ("bin", "schemas", "templates", "instructions")
34
+ COPY_EXCLUSIONS = {"bin/bump-version"}
35
+ HOOK_RUNTIME_FILES = (
36
+ "hooks/run-hook.cmd",
37
+ "hooks/adr-hook.py",
38
+ "hooks/adr_hook_core.py",
39
+ "hooks/adr_pr_guard.py",
40
+ # The guard derives its judge timeout from the declared runner budget, so
41
+ # every client tree needs the declaration. Without it the mirrors silently
42
+ # fall back to a constant, and the constant stops matching the moment
43
+ # somebody changes the budget -- which is the drift this whole change is
44
+ # about, reintroduced one directory over.
45
+ "hooks/manifest.json",
46
+ "hooks/adapters/__init__.py",
47
+ "hooks/adapters/claude.py",
48
+ "hooks/adapters/codex.py",
49
+ "hooks/adapters/copilot.py",
50
+ "hooks/bin/windows-x64/adr-hook.exe",
51
+ )
52
+ # The modules bin/ entrypoints import from OUTSIDE bin/. Mirrored at their own
53
+ # relative paths, because bin/adr-doctor resolves them by appending ROOT and
54
+ # ROOT/"scripts" to sys.path -- so the layout has to match, not just the files.
55
+ #
56
+ # COPY_ROOTS cannot carry these: declared_source_files() rglobs a whole root, so
57
+ # adding "scripts" would drag build-client-adapters.py into the mirrors and copy
58
+ # clients/workflows.json there too.
59
+ #
60
+ # That last file is why the exclusions below are load-bearing rather than
61
+ # tidiness. adr_doctor_models.generated_tree_owner() identifies a generated tree
62
+ # by the ABSENCE of clients/workflows.json -- it is the generator's input, and a
63
+ # canonical payload root always has it. Mirror it and the doctor stops degrading
64
+ # and starts hard-failing again, silently.
65
+ #
66
+ # Import closure verified: all eight are stdlib-only except
67
+ # clients/installer/__init__.py -> .contracts and detection.py -> .contracts,
68
+ # both of which are in the list. The two __init__.py files are one-line
69
+ # docstrings and are included so the static invariant test and the runtime
70
+ # importer agree; without them these would resolve only as implicit namespace
71
+ # packages.
72
+ RUNTIME_SUPPORT_FILES = (
73
+ "clients/__init__.py",
74
+ "clients/installer/__init__.py",
75
+ # Mirrored because bin/adr_doctor_probes.py imports it, and bin/ ships into
76
+ # every generated tree. Stdlib-only, like every other file in this list.
77
+ "clients/installer/bounded.py",
78
+ "clients/installer/contracts.py",
79
+ "clients/installer/detection.py",
80
+ "hooks/__init__.py",
81
+ "hooks/hook_benchmark.py",
82
+ "scripts/adr_settings.py",
83
+ "scripts/project_setup.py",
84
+ )
85
+ SOURCE_FILES = (
86
+ "clients/capabilities.json",
87
+ "clients/exceptions.json",
88
+ "clients/workflows.json",
89
+ "hooks/manifest.json",
90
+ "packaging/dependencies-source.json",
91
+ "packaging/executables-source.json",
92
+ "packaging/public-artifacts.json",
93
+ ".claude-plugin/plugin.json",
94
+ ".claude-plugin/marketplace.json",
95
+ ".mcp.json",
96
+ ".agents/plugins/marketplace.json",
97
+ "codex/.codex-plugin/plugin.json",
98
+ ".github/plugin/marketplace.json",
99
+ "copilot/plugin.json",
100
+ "codex/.mcp.json",
101
+ "copilot/.mcp.json",
102
+ )
103
+ PROVENANCE = "Generated by scripts/build-client-adapters.py from clients/workflows.json"
104
+ CACHE_VERSION = 1
105
+
106
+
107
+ class GenerationError(RuntimeError):
108
+ """A deterministic input, validation, or drift failure."""
109
+
110
+
111
+ @dataclass
112
+ class Stats:
113
+ files_read: int = 0
114
+ bytes_read: int = 0
115
+ files_written: int = 0
116
+ bytes_written: int = 0
117
+ unchanged: int = 0
118
+
119
+ def as_dict(self) -> dict[str, int]:
120
+ return {
121
+ "files_read": self.files_read,
122
+ "bytes_read": self.bytes_read,
123
+ "files_written": self.files_written,
124
+ "bytes_written": self.bytes_written,
125
+ "unchanged": self.unchanged,
126
+ }
127
+
128
+
129
+ def read(path: Path, stats: Stats) -> bytes:
130
+ data = path.read_bytes()
131
+ stats.files_read += 1
132
+ stats.bytes_read += len(data)
133
+ return data
134
+
135
+
136
+ def read_json(path: Path, stats: Stats) -> object:
137
+ try:
138
+ return json.loads(read(path, stats).decode("utf-8"))
139
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
140
+ raise GenerationError(f"invalid JSON: {path}: {exc}") from exc
141
+
142
+
143
+ def encoded_json(value: object) -> bytes:
144
+ return (json.dumps(value, indent=2, ensure_ascii=False) + "\n").encode("utf-8")
145
+
146
+
147
+ def write(path: Path, content: bytes, mode: int | None, stats: Stats) -> None:
148
+ path.parent.mkdir(parents=True, exist_ok=True)
149
+ temporary = path.with_name(
150
+ f".{path.name}.{os.getpid()}.{threading.get_ident()}.tmp"
151
+ )
152
+ try:
153
+ with temporary.open("xb") as stream:
154
+ stream.write(content)
155
+ if mode is not None:
156
+ temporary.chmod(mode)
157
+ os.replace(temporary, path)
158
+ except BaseException:
159
+ try:
160
+ temporary.unlink()
161
+ except FileNotFoundError:
162
+ pass
163
+ raise
164
+ stats.files_written += 1
165
+ stats.bytes_written += len(content)
166
+
167
+
168
+ def expected_version(root: Path, stats: Stats) -> str:
169
+ text = read(root / "CHANGELOG.md", stats).decode("utf-8")
170
+ match = re.search(r"^## \[(\d+\.\d+\.\d+)\]", text, re.MULTILINE)
171
+ if not match:
172
+ raise GenerationError("CHANGELOG.md has no stable release heading")
173
+ return match.group(1)
@@ -0,0 +1,260 @@
1
+ """Release allowlisting and warm-state cache for client generation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import fnmatch
6
+ import hashlib
7
+ import json
8
+ import os
9
+ import stat
10
+ import tempfile
11
+ from concurrent.futures import ThreadPoolExecutor
12
+ from pathlib import Path
13
+ from typing import Iterable
14
+
15
+ from client_generation_model import (
16
+ CACHE_VERSION,
17
+ SOURCE_FILES,
18
+ GenerationError,
19
+ Stats,
20
+ encoded_json,
21
+ )
22
+
23
+
24
+ def _safe_release_path(path: str, allowlist: dict) -> bool:
25
+ normalized = path.replace("\\", "/")
26
+ if normalized.startswith("./"):
27
+ normalized = normalized[2:]
28
+ segments = set(normalized.split("/"))
29
+ for forbidden in allowlist.get("forbidden_segments", []):
30
+ token = forbidden.replace("\\", "/").strip("/")
31
+ if "/" not in token and token in segments:
32
+ return False
33
+ if normalized == token or normalized.startswith(token + "/"):
34
+ return False
35
+ for pattern in allowlist.get("forbidden_globs", []):
36
+ portable = pattern.replace("\\", "/")
37
+ if fnmatch.fnmatchcase(normalized, portable):
38
+ return False
39
+ if portable.startswith("**/") and fnmatch.fnmatchcase(
40
+ normalized, portable[3:]
41
+ ):
42
+ return False
43
+ return any(
44
+ normalized == item or normalized.startswith(item.rstrip("/") + "/")
45
+ for item in allowlist.get("include_roots", [])
46
+ )
47
+
48
+
49
+ def validate_release_paths(paths: Iterable[str], allowlist: dict) -> list[str]:
50
+ return sorted(path for path in paths if not _safe_release_path(path, allowlist))
51
+
52
+
53
+ def collect_release_files(root: Path, allowlist: dict) -> list[str]:
54
+ """Collect only declared public files without traversing the repository root."""
55
+ files: set[str] = set()
56
+ invalid_roots = validate_release_paths(
57
+ allowlist.get("include_roots", []),
58
+ allowlist,
59
+ )
60
+ if invalid_roots:
61
+ raise GenerationError(
62
+ "forbidden public root selected: " + ", ".join(invalid_roots)
63
+ )
64
+ for declared in sorted(allowlist.get("include_roots", [])):
65
+ path = root / declared
66
+ if not path.exists():
67
+ raise GenerationError(f"missing public artifact: {declared}")
68
+ candidates = [path] if path.is_file() else path.rglob("*")
69
+ for candidate in candidates:
70
+ if candidate.is_symlink():
71
+ raise GenerationError(
72
+ f"public artifact symlink is not allowed: "
73
+ f"{candidate.relative_to(root).as_posix()}"
74
+ )
75
+ if candidate.is_file():
76
+ relative = candidate.relative_to(root).as_posix()
77
+ if not validate_release_paths([relative], allowlist):
78
+ files.add(relative)
79
+ return sorted(files)
80
+
81
+
82
+ def _cache_path(output_root: Path) -> Path:
83
+ key = hashlib.sha256(str(output_root).encode("utf-8")).hexdigest()[:24]
84
+ return Path(tempfile.gettempdir()) / "adr-kit-client-generation" / f"{key}.json"
85
+
86
+
87
+ def _source_stamps(source_root: Path, source_paths: list[Path]) -> list[list[object]]:
88
+ paths = [source_root / name for name in SOURCE_FILES]
89
+ paths.extend(
90
+ (
91
+ source_root / "CHANGELOG.md",
92
+ source_root / "scripts/build-client-adapters.py",
93
+ source_root / "scripts/client_generation.py",
94
+ source_root / "scripts/client_generation_artifacts.py",
95
+ source_root / "scripts/client_generation_model.py",
96
+ source_root / "scripts/client_generation_state.py",
97
+ )
98
+ )
99
+ paths.extend(source_paths)
100
+ ordered = sorted(set(paths), key=lambda item: item.as_posix())
101
+
102
+ def stamp(path: Path) -> list[object]:
103
+ info = path.stat()
104
+ return [
105
+ path.relative_to(source_root).as_posix(),
106
+ info.st_size,
107
+ info.st_mtime_ns,
108
+ stat.S_IMODE(info.st_mode),
109
+ ]
110
+
111
+ with ThreadPoolExecutor(max_workers=min(16, max(1, len(ordered)))) as pool:
112
+ return list(pool.map(stamp, ordered))
113
+
114
+
115
+ def load_early_state(
116
+ source_root: Path,
117
+ output_root: Path,
118
+ source_paths: list[Path],
119
+ stats: Stats,
120
+ ) -> bool:
121
+ try:
122
+ state = json.loads(_cache_path(output_root).read_text(encoding="utf-8"))
123
+ if not isinstance(state, dict) or state.get("schema_version") != CACHE_VERSION:
124
+ return False
125
+ if state.get("sources") != _source_stamps(source_root, source_paths):
126
+ return False
127
+ files = state.get("files")
128
+ if not isinstance(files, dict):
129
+ return False
130
+ ordered_files = sorted(files.items())
131
+
132
+ def current_stamp(item: tuple[str, object]) -> list[object]:
133
+ current = (output_root / item[0]).stat()
134
+ return [
135
+ current.st_size,
136
+ current.st_mtime_ns,
137
+ stat.S_IMODE(current.st_mode),
138
+ ]
139
+
140
+ with ThreadPoolExecutor(
141
+ max_workers=min(16, max(1, len(ordered_files)))
142
+ ) as pool:
143
+ current_stamps = list(pool.map(current_stamp, ordered_files))
144
+ if any(
145
+ current != recorded
146
+ for current, (_relative, recorded) in zip(
147
+ current_stamps, ordered_files
148
+ )
149
+ ):
150
+ return False
151
+ directories = state.get("directories")
152
+ if not isinstance(directories, dict):
153
+ return False
154
+ for relative, recorded in directories.items():
155
+ path = output_root / relative
156
+ current = path.stat().st_mtime_ns if path.is_dir() else None
157
+ if current != recorded:
158
+ return False
159
+ stats.unchanged = len(files)
160
+ return True
161
+ except (
162
+ GenerationError,
163
+ FileNotFoundError,
164
+ OSError,
165
+ ValueError,
166
+ TypeError,
167
+ json.JSONDecodeError,
168
+ ):
169
+ return False
170
+
171
+
172
+ def _expected_fingerprint(expected: dict[str, tuple[bytes, int | None]]) -> str:
173
+ digest = hashlib.sha256(b"adr-kit-client-generation-v1\0")
174
+ for relative, (content, mode) in sorted(expected.items()):
175
+ digest.update(relative.encode("utf-8"))
176
+ digest.update(b"\0")
177
+ digest.update(str(mode).encode("ascii"))
178
+ digest.update(b"\0")
179
+ digest.update(content)
180
+ return digest.hexdigest()
181
+
182
+
183
+ def load_fast_state(
184
+ output_root: Path,
185
+ expected: dict[str, tuple[bytes, int | None]],
186
+ generated_roots: list[str],
187
+ ) -> bool:
188
+ try:
189
+ state = json.loads(_cache_path(output_root).read_text(encoding="utf-8"))
190
+ if state.get("fingerprint") != _expected_fingerprint(expected):
191
+ return False
192
+ files = state.get("files")
193
+ if not isinstance(files, dict) or set(files) != set(expected):
194
+ return False
195
+ for relative, recorded in files.items():
196
+ current = (output_root / relative).stat()
197
+ if [
198
+ current.st_size,
199
+ current.st_mtime_ns,
200
+ stat.S_IMODE(current.st_mode),
201
+ ] != recorded:
202
+ return False
203
+ directories = state.get("directories")
204
+ if not isinstance(directories, dict):
205
+ return False
206
+ for relative in generated_roots:
207
+ path = output_root / relative
208
+ current = path.stat().st_mtime_ns if path.is_dir() else None
209
+ if directories.get(relative) != current:
210
+ return False
211
+ return True
212
+ except (FileNotFoundError, OSError, ValueError, TypeError, json.JSONDecodeError):
213
+ return False
214
+
215
+
216
+ def save_fast_state(
217
+ source_root: Path,
218
+ output_root: Path,
219
+ source_paths: list[Path],
220
+ expected: dict[str, tuple[bytes, int | None]],
221
+ generated_roots: list[str],
222
+ ) -> None:
223
+ files = {}
224
+ for relative in expected:
225
+ current = (output_root / relative).stat()
226
+ files[relative] = [
227
+ current.st_size,
228
+ current.st_mtime_ns,
229
+ stat.S_IMODE(current.st_mode),
230
+ ]
231
+ directories = {}
232
+ for relative in generated_roots:
233
+ path = output_root / relative
234
+ directories[relative] = path.stat().st_mtime_ns if path.is_dir() else None
235
+ state = {
236
+ "schema_version": CACHE_VERSION,
237
+ "sources": _source_stamps(source_root, source_paths),
238
+ "fingerprint": _expected_fingerprint(expected),
239
+ "files": files,
240
+ "directories": directories,
241
+ }
242
+ destination = _cache_path(output_root)
243
+ destination.parent.mkdir(parents=True, exist_ok=True)
244
+ content = encoded_json(state)
245
+ try:
246
+ if destination.read_bytes() == content:
247
+ return
248
+ except FileNotFoundError:
249
+ pass
250
+ descriptor, temporary = tempfile.mkstemp(prefix=".state.", dir=destination.parent)
251
+ try:
252
+ with os.fdopen(descriptor, "wb") as stream:
253
+ stream.write(content)
254
+ os.replace(temporary, destination)
255
+ except BaseException:
256
+ try:
257
+ os.unlink(temporary)
258
+ except FileNotFoundError:
259
+ pass
260
+ raise