@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.
- package/.claude-plugin/plugin.json +29 -0
- package/LICENSE +21 -0
- package/README.md +850 -0
- package/bin/adr +1552 -0
- package/bin/adr-audit +454 -0
- package/bin/adr-context +584 -0
- package/bin/adr-discover +546 -0
- package/bin/adr-doctor +166 -0
- package/bin/adr-generate-scripts +421 -0
- package/bin/adr-grill-signal +131 -0
- package/bin/adr-guardian +1263 -0
- package/bin/adr-index +199 -0
- package/bin/adr-judge +2832 -0
- package/bin/adr-judge-precommit +87 -0
- package/bin/adr-lint +2087 -0
- package/bin/adr-mcp +1093 -0
- package/bin/adr-migrate +644 -0
- package/bin/adr-quality +275 -0
- package/bin/adr-readiness +211 -0
- package/bin/adr-readiness-ci +111 -0
- package/bin/adr-related +401 -0
- package/bin/adr-renumber +254 -0
- package/bin/adr-retire +467 -0
- package/bin/adr-settings +399 -0
- package/bin/adr-status +797 -0
- package/bin/adr-suggest +803 -0
- package/bin/adr-watch +674 -0
- package/bin/adr_catalog.py +536 -0
- package/bin/adr_config.py +280 -0
- package/bin/adr_doctor_checks.py +407 -0
- package/bin/adr_doctor_core.py +342 -0
- package/bin/adr_doctor_models.py +186 -0
- package/bin/adr_doctor_probes.py +216 -0
- package/bin/adr_format.py +786 -0
- package/bin/adr_grill_signal.py +123 -0
- package/bin/adr_guardian_queue.py +218 -0
- package/bin/adr_history_scan.py +278 -0
- package/bin/adr_index_core.py +443 -0
- package/bin/adr_llm.py +333 -0
- package/bin/adr_llm_judge_migration.py +314 -0
- package/bin/adr_quality_core.py +674 -0
- package/bin/adr_query.py +678 -0
- package/bin/adr_readiness.py +442 -0
- package/bin/adr_readiness_ci.py +123 -0
- package/bin/adr_regex.py +165 -0
- package/bin/adr_regex_worker.py +30 -0
- package/bin/adr_retrieval_health.py +385 -0
- package/bin/adr_schema.py +448 -0
- package/bin/adr_state.py +172 -0
- package/bin/bump-version +71 -0
- package/clients/workflows.json +229 -0
- package/hooks/__init__.py +1 -0
- package/hooks/adapters/__init__.py +13 -0
- package/hooks/adapters/claude.py +27 -0
- package/hooks/adapters/codex.py +26 -0
- package/hooks/adapters/copilot.py +11 -0
- package/hooks/adr-hook.py +128 -0
- package/hooks/adr_hook_core.py +843 -0
- package/hooks/adr_pr_guard.py +367 -0
- package/instructions/ADR-guide.md +48 -0
- package/instructions/adr.coding.md +82 -0
- package/instructions/adr.review.md +182 -0
- package/opencode/plugin.ts +451 -0
- package/package.json +41 -0
- package/schemas/adr-context-probes.schema.json +56 -0
- package/schemas/adr-enforcement.schema.json +57 -0
- package/schemas/adr-frontmatter.schema.json +144 -0
- package/schemas/adr-index.schema.json +276 -0
- package/schemas/adr-kit-config.schema.json +371 -0
- package/schemas/adr-readiness.schema.json +41 -0
- package/schemas/client-capabilities.schema.json +503 -0
- package/schemas/client-certification.schema.json +101 -0
- package/schemas/doctor-output.schema.json +92 -0
- package/schemas/marketplace.json.schema.json +70 -0
- package/schemas/plugin.json.schema.json +67 -0
- package/scripts/adr_settings.py +239 -0
- package/scripts/benchmark-adr-grilling.py +323 -0
- package/scripts/benchmark-client-generation.py +178 -0
- package/scripts/build-client-adapters.py +139 -0
- package/scripts/bump-version.py +304 -0
- package/scripts/check-branch-sync.py +243 -0
- package/scripts/check-release-version.py +81 -0
- package/scripts/client_certification.py +153 -0
- package/scripts/client_evidence.py +280 -0
- package/scripts/client_generation.py +288 -0
- package/scripts/client_generation_artifacts.py +351 -0
- package/scripts/client_generation_model.py +173 -0
- package/scripts/client_generation_state.py +260 -0
- package/scripts/client_support_matrix.py +360 -0
- package/scripts/install-agent-envs.py +300 -0
- package/scripts/probe-client-events.py +183 -0
- package/scripts/project_setup.py +379 -0
- package/scripts/refresh-otgw-corpus.py +219 -0
- package/scripts/settings.py +81 -0
- package/scripts/setup-project.py +205 -0
- package/scripts/sync-agent-plugins.py +17 -0
- package/scripts/version_sites.py +377 -0
- package/skills/adr/SKILL.md +780 -0
- package/skills/audit/SKILL.md +103 -0
- package/skills/context/SKILL.md +77 -0
- package/skills/grill/SKILL.md +84 -0
- package/skills/grill/agents/openai.yaml +4 -0
- package/skills/guardian/SKILL.md +316 -0
- package/skills/init/SKILL.md +499 -0
- package/skills/install-hooks/SKILL.md +154 -0
- package/skills/judge/SKILL.md +168 -0
- package/skills/lint/SKILL.md +321 -0
- package/skills/migrate/SKILL.md +313 -0
- package/skills/related/SKILL.md +62 -0
- package/skills/retire/SKILL.md +41 -0
- package/skills/review/SKILL.md +167 -0
- package/skills/settings/SKILL.md +73 -0
- package/skills/setup/SKILL.md +128 -0
- package/skills/supersede/SKILL.md +136 -0
- package/skills/upgrade/SKILL.md +273 -0
- package/templates/adr-kit-guide.md +354 -0
- package/templates/adr-template.canonical.md +115 -0
- package/templates/adr-template.madr.md +131 -0
- package/templates/adr-template.md +131 -0
- package/templates/adr-template.nygard.md +111 -0
- package/templates/cc-settings/guardian-hook-entry.json +9 -0
- package/templates/githooks/pre-commit +337 -0
- package/templates/github-workflows/adr-audit.yml +58 -0
- package/templates/github-workflows/adr-guardian-audit.yml +133 -0
- package/templates/github-workflows/adr-index-check.yml +30 -0
- package/templates/github-workflows/adr-judge.yml +31 -0
- package/templates/github-workflows/adr-readiness.yml +18 -0
- package/templates/validate_adr_template.py +38 -0
- package/templates/validate_adr_template.sh +74 -0
|
@@ -0,0 +1,360 @@
|
|
|
1
|
+
"""Render the evidence-backed support document from the canonical registries.
|
|
2
|
+
|
|
3
|
+
Split out of `client_certification.py`, which had grown past the 400-line
|
|
4
|
+
support-module budget ADR-010 sets and `tests/test_release_allowlist.py`
|
|
5
|
+
enforces. The split follows the seam the module docstring already described:
|
|
6
|
+
that file *validates* certification evidence, this one *renders* the claims.
|
|
7
|
+
|
|
8
|
+
Every section here derives its content from a registry rather than asserting
|
|
9
|
+
it. That is not a style preference -- it is the correction TASK-115 and
|
|
10
|
+
TASK-138 both landed, and the reason each renderer states its own source.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
CLIENTS = ("claude-code-cli", "codex-cli", "github-copilot-cli")
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
#: Which manifest event answers each column of the lifecycle table.
|
|
19
|
+
LIFECYCLE_COLUMNS = (
|
|
20
|
+
("Session global", "session-start"),
|
|
21
|
+
("Prompt/task query", "user-prompt-submit"),
|
|
22
|
+
("Edit query", "pre-tool-use"),
|
|
23
|
+
("Post-edit backstop", "post-tool-use"),
|
|
24
|
+
("Plan exit", "plan-exit"),
|
|
25
|
+
("Shell tool / PR moment", "pr-create"),
|
|
26
|
+
("Subagent", "subagent-start"),
|
|
27
|
+
("Compaction", "pre-compact"),
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _lifecycle_rows(labels: dict) -> list:
|
|
32
|
+
"""Derive the lifecycle table from the manifest instead of asserting it.
|
|
33
|
+
|
|
34
|
+
These rows were three hardcoded strings, which is exactly why the document
|
|
35
|
+
could claim capabilities that did not exist: nothing derived them, so
|
|
36
|
+
nothing could contradict them. `Plan exit | supported (ExitPlanMode)` stayed
|
|
37
|
+
true-looking for as long as somebody had typed it, through a release in
|
|
38
|
+
which that event never fired at all.
|
|
39
|
+
|
|
40
|
+
Now each cell is the manifest's own answer for that client -- the native
|
|
41
|
+
event name when the client offers the moment, and an explicit "no native
|
|
42
|
+
event" when it does not. A capability cannot appear here unless it is
|
|
43
|
+
registered, and `--check` fails the build when the file drifts from the
|
|
44
|
+
manifest.
|
|
45
|
+
|
|
46
|
+
Falls back to a stated absence rather than raising: this renderer runs
|
|
47
|
+
inside release certification, and a missing manifest should fail the
|
|
48
|
+
manifest's own gate, not the document that reads it.
|
|
49
|
+
"""
|
|
50
|
+
import json
|
|
51
|
+
from pathlib import Path as _Path
|
|
52
|
+
|
|
53
|
+
manifest_path = _Path(__file__).resolve().parents[1] / "hooks" / "manifest.json"
|
|
54
|
+
try:
|
|
55
|
+
events = {
|
|
56
|
+
event["id"]: event
|
|
57
|
+
for event in json.loads(manifest_path.read_text(encoding="utf-8"))["events"]
|
|
58
|
+
}
|
|
59
|
+
except (OSError, ValueError, KeyError, TypeError):
|
|
60
|
+
return [
|
|
61
|
+
"",
|
|
62
|
+
"## Lifecycle retrieval support",
|
|
63
|
+
"",
|
|
64
|
+
"_Unavailable: hooks/manifest.json could not be read, so no claim is"
|
|
65
|
+
" made here rather than an unverified one._",
|
|
66
|
+
]
|
|
67
|
+
|
|
68
|
+
header = " | ".join(name for name, _ in LIFECYCLE_COLUMNS)
|
|
69
|
+
rows = [
|
|
70
|
+
"",
|
|
71
|
+
"## Lifecycle retrieval support",
|
|
72
|
+
"",
|
|
73
|
+
"Derived from `hooks/manifest.json`, which is the registry of what each",
|
|
74
|
+
"client is *wired for*. A cell names that client's own event, or states",
|
|
75
|
+
"that the client offers none.",
|
|
76
|
+
"",
|
|
77
|
+
"This table makes one claim and not two. It says a moment is registered;",
|
|
78
|
+
"it does not say the wiring behind it works. That second question belongs",
|
|
79
|
+
"to the dispatch tests, which drive every registered event through the",
|
|
80
|
+
"real entrypoint on every client -- and it is a question worth keeping",
|
|
81
|
+
"separate, because `Plan exit | supported (ExitPlanMode)` sat in this file",
|
|
82
|
+
"through a release in which that event never fired. The Evidence column",
|
|
83
|
+
"above says how the wiring was verified.",
|
|
84
|
+
"",
|
|
85
|
+
f"| Client | {header} |",
|
|
86
|
+
"|---|" + "---|" * len(LIFECYCLE_COLUMNS),
|
|
87
|
+
]
|
|
88
|
+
for client in CLIENTS:
|
|
89
|
+
cells = []
|
|
90
|
+
for _name, event_id in LIFECYCLE_COLUMNS:
|
|
91
|
+
event = events.get(event_id)
|
|
92
|
+
native = (event or {}).get("clients", {}).get(client)
|
|
93
|
+
if not native:
|
|
94
|
+
cells.append("no native event")
|
|
95
|
+
continue
|
|
96
|
+
matcher = (event or {}).get("matcher")
|
|
97
|
+
# A matcher is a regex alternation, so its pipes have to be escaped
|
|
98
|
+
# or they end the table cell and silently shift every column right.
|
|
99
|
+
escaped = str(matcher).replace("|", r"\|") if matcher else ""
|
|
100
|
+
cells.append(f"`{native}`" + (f" / `{escaped}`" if matcher else ""))
|
|
101
|
+
rows.append(f"| {labels[client]} | " + " | ".join(cells) + " |")
|
|
102
|
+
return rows
|
|
103
|
+
|
|
104
|
+
def _enforcement_rows(labels: dict) -> list:
|
|
105
|
+
"""State which tiers block, from the two files that decide it.
|
|
106
|
+
|
|
107
|
+
This section replaces a hardcoded paragraph that attributed to ADR-004 the
|
|
108
|
+
option ADR-004 rejected: it called the pre-edit tier "the *fail-closed*
|
|
109
|
+
floor of the injection model". ADR-004 says the opposite twice -- injection
|
|
110
|
+
hooks "never block; they steer", and a fail-closed edit gate is listed under
|
|
111
|
+
the rejected alternatives ("Blocking belongs at commit, not keystroke").
|
|
112
|
+
The paragraph then contradicted itself four sentences later by naming the
|
|
113
|
+
pre-commit hook as the enforcement that does not weaken.
|
|
114
|
+
|
|
115
|
+
It was hardcoded, which is the same reason `_lifecycle_rows` gives for the
|
|
116
|
+
claims it had to remove: nothing derived it, so nothing could contradict it.
|
|
117
|
+
The per-client half is now the manifest's own answer plus whatever
|
|
118
|
+
`clients/capabilities.json` declares, so a tier cannot be claimed here
|
|
119
|
+
unless it is registered, and cannot be claimed as enforcing on a client that
|
|
120
|
+
declares it advisory.
|
|
121
|
+
|
|
122
|
+
Falls back to a stated absence rather than raising, for the same reason
|
|
123
|
+
`_lifecycle_rows` does.
|
|
124
|
+
"""
|
|
125
|
+
manifest, capabilities = _read_contract_sources()
|
|
126
|
+
if manifest is None or capabilities is None:
|
|
127
|
+
return [
|
|
128
|
+
"",
|
|
129
|
+
"## Where enforcement is fail-closed",
|
|
130
|
+
"",
|
|
131
|
+
"_Unavailable: `hooks/manifest.json` or `clients/capabilities.json`"
|
|
132
|
+
" could not be read, so no claim is made here rather than an"
|
|
133
|
+
" unverified one._",
|
|
134
|
+
]
|
|
135
|
+
|
|
136
|
+
pr_clients = manifest.get("pr-create", {}).get("clients", {})
|
|
137
|
+
rows = [
|
|
138
|
+
"",
|
|
139
|
+
"## Where enforcement is fail-closed",
|
|
140
|
+
"",
|
|
141
|
+
"Derived from `hooks/manifest.json` and `clients/capabilities.json`.",
|
|
142
|
+
"",
|
|
143
|
+
"ADR-004 puts all three injection tiers -- session, edit and task -- on",
|
|
144
|
+
"the fail-open side without exception: they steer, and none of them",
|
|
145
|
+
"blocks. It rejected a fail-closed edit gate by name, because legitimate",
|
|
146
|
+
"compliant edits touch governed paths constantly, so blocking belongs at",
|
|
147
|
+
"commit rather than at keystroke. There is no pre-edit floor on any",
|
|
148
|
+
"client, and the absence of one is not a degradation.",
|
|
149
|
+
"",
|
|
150
|
+
"Two tiers block, and neither is an injection tier:",
|
|
151
|
+
"",
|
|
152
|
+
"* **Commit tier** (ADR-004) -- `bin/adr-judge` at pre-commit and in CI.",
|
|
153
|
+
" Client-independent, because `git commit` happens whether or not an",
|
|
154
|
+
" agent is running. A violation is caught before the commit lands on",
|
|
155
|
+
" every client in this table, and on no client at all.",
|
|
156
|
+
"* **Pull-request tier** (ADR-023) -- `hooks/adr_pr_guard.py` on",
|
|
157
|
+
" `gh pr create`. Client-qualified: a client that has no permission",
|
|
158
|
+
" decision to return cannot stop the tool call, and where it cannot the",
|
|
159
|
+
" branch is still judged and the verdict shown, labelled as advisory.",
|
|
160
|
+
"",
|
|
161
|
+
"| Client | Pull-request tier |",
|
|
162
|
+
"|---|---|",
|
|
163
|
+
]
|
|
164
|
+
for client in CLIENTS:
|
|
165
|
+
advisory = next(
|
|
166
|
+
(
|
|
167
|
+
entry
|
|
168
|
+
for entry in _degradations(capabilities, client)
|
|
169
|
+
if entry.get("outcome") == "enforcement"
|
|
170
|
+
),
|
|
171
|
+
None,
|
|
172
|
+
)
|
|
173
|
+
if not pr_clients.get(client):
|
|
174
|
+
cell = "no native event: the commit tier is the only floor here"
|
|
175
|
+
elif advisory:
|
|
176
|
+
cell = f"advisory only (`{advisory.get('id', 'declared degradation')}`)"
|
|
177
|
+
else:
|
|
178
|
+
cell = f"enforced at `{pr_clients[client]}`"
|
|
179
|
+
rows.append(f"| {labels[client]} | {cell} |")
|
|
180
|
+
return rows
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def _degradation_rows(labels: dict) -> list:
|
|
184
|
+
"""Render every declared degradation, and claim no others.
|
|
185
|
+
|
|
186
|
+
The heading this replaces named one degradation for one client in prose.
|
|
187
|
+
Prose cannot be checked against the registry, so the section could describe
|
|
188
|
+
a weakening that was never declared -- which is what it did.
|
|
189
|
+
"""
|
|
190
|
+
_manifest, capabilities = _read_contract_sources()
|
|
191
|
+
if capabilities is None:
|
|
192
|
+
return []
|
|
193
|
+
rows = [
|
|
194
|
+
"",
|
|
195
|
+
"## Known degradations",
|
|
196
|
+
"",
|
|
197
|
+
"Every entry is declared in `clients/capabilities.json`, with its reason,",
|
|
198
|
+
"its user-visible effect and the backstop that still holds (ADR-010,",
|
|
199
|
+
"ADR-023). A weakening that is not declared there does not appear here.",
|
|
200
|
+
"",
|
|
201
|
+
"| Client | Outcome | Reason | User effect | Backstop |",
|
|
202
|
+
"|---|---|---|---|---|",
|
|
203
|
+
]
|
|
204
|
+
found = False
|
|
205
|
+
for client in CLIENTS:
|
|
206
|
+
for entry in _degradations(capabilities, client):
|
|
207
|
+
found = True
|
|
208
|
+
cells = [
|
|
209
|
+
labels[client],
|
|
210
|
+
f"`{entry.get('outcome', '?')}`",
|
|
211
|
+
str(entry.get("reason", "")).replace("|", r"\|"),
|
|
212
|
+
str(entry.get("user_effect", "")).replace("|", r"\|"),
|
|
213
|
+
str(entry.get("backstop", "")).replace("|", r"\|"),
|
|
214
|
+
]
|
|
215
|
+
rows.append("| " + " | ".join(cells) + " |")
|
|
216
|
+
return rows if found else []
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def _degradations(capabilities: dict, client: str) -> list:
|
|
220
|
+
for entry in capabilities.get("clients", []):
|
|
221
|
+
if isinstance(entry, dict) and entry.get("id") == client:
|
|
222
|
+
declared = entry.get("degradations")
|
|
223
|
+
return [item for item in declared if isinstance(item, dict)] if isinstance(declared, list) else []
|
|
224
|
+
return []
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
def _read_contract_sources() -> tuple:
|
|
228
|
+
"""The manifest events by id and the capability registry, or (None, None)."""
|
|
229
|
+
import json
|
|
230
|
+
from pathlib import Path as _Path
|
|
231
|
+
|
|
232
|
+
root = _Path(__file__).resolve().parents[1]
|
|
233
|
+
try:
|
|
234
|
+
events = {
|
|
235
|
+
event["id"]: event
|
|
236
|
+
for event in json.loads(
|
|
237
|
+
(root / "hooks" / "manifest.json").read_text(encoding="utf-8")
|
|
238
|
+
)["events"]
|
|
239
|
+
}
|
|
240
|
+
except (OSError, ValueError, KeyError, TypeError):
|
|
241
|
+
events = None
|
|
242
|
+
try:
|
|
243
|
+
capabilities = json.loads(
|
|
244
|
+
(root / "clients" / "capabilities.json").read_text(encoding="utf-8")
|
|
245
|
+
)
|
|
246
|
+
except (OSError, ValueError):
|
|
247
|
+
capabilities = None
|
|
248
|
+
return events, capabilities
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def _probe_rows(labels: dict) -> list:
|
|
252
|
+
"""Report what a real client answered, separately from what we believe.
|
|
253
|
+
|
|
254
|
+
The table above is derived from our own manifest, so it says what adr-kit is
|
|
255
|
+
wired for. This section says what an installed binary actually emitted, and
|
|
256
|
+
the two are deliberately not merged: every hook defect this kit has shipped
|
|
257
|
+
was an event we had registered and the client never reached, and a document
|
|
258
|
+
that folds the two together cannot show that gap.
|
|
259
|
+
|
|
260
|
+
Absent evidence is `not-run`, never `unsupported`. A probe that did not run,
|
|
261
|
+
or a prompt that used no tools, proves nothing about a capability -- and
|
|
262
|
+
writing the stronger word is exactly how this document acquired the claims
|
|
263
|
+
it had to be rewritten to remove.
|
|
264
|
+
"""
|
|
265
|
+
import json
|
|
266
|
+
from pathlib import Path as _Path
|
|
267
|
+
|
|
268
|
+
root = _Path(__file__).resolve().parents[1]
|
|
269
|
+
probes = sorted((root / "tests" / "certification").glob("probe-*.json"))
|
|
270
|
+
if not probes:
|
|
271
|
+
return []
|
|
272
|
+
records = []
|
|
273
|
+
for path in probes:
|
|
274
|
+
try:
|
|
275
|
+
payload = json.loads(path.read_text(encoding="utf-8"))
|
|
276
|
+
except (OSError, ValueError):
|
|
277
|
+
continue
|
|
278
|
+
for record in payload.get("records", []):
|
|
279
|
+
if isinstance(record, dict) and record.get("client") in labels:
|
|
280
|
+
records.append((path.name, record))
|
|
281
|
+
if not records:
|
|
282
|
+
return []
|
|
283
|
+
|
|
284
|
+
rows = [
|
|
285
|
+
"",
|
|
286
|
+
"## Observed client evidence",
|
|
287
|
+
"",
|
|
288
|
+
"What an installed binary reported, from its own event stream. Separate",
|
|
289
|
+
"from the table above on purpose: that one says what adr-kit is wired",
|
|
290
|
+
"for, this one says what a client did. Every hook defect this kit has",
|
|
291
|
+
"shipped lived in the gap between the two.",
|
|
292
|
+
"",
|
|
293
|
+
"An event that does not appear here is `not-observed`, not unsupported.",
|
|
294
|
+
"A probe run that used no tools cannot produce a tool event, and reading",
|
|
295
|
+
"that silence as a missing capability is how this document acquired the",
|
|
296
|
+
"claims it had to be rewritten to remove.",
|
|
297
|
+
"",
|
|
298
|
+
"| Client | Version | Platform | Evidence | Observed events |",
|
|
299
|
+
"|---|---|---|---|---|",
|
|
300
|
+
]
|
|
301
|
+
for source, record in records:
|
|
302
|
+
observed = record.get("observed_events") or []
|
|
303
|
+
detail = (
|
|
304
|
+
", ".join(f"`{event}`" for event in observed)
|
|
305
|
+
if observed
|
|
306
|
+
else f"_{record.get('reason', 'not run')}_"
|
|
307
|
+
)
|
|
308
|
+
rows.append(
|
|
309
|
+
f"| {labels[record['client']]} | {record.get('version') or 'unknown'} | "
|
|
310
|
+
f"{record.get('platform') or 'unknown'} | {record.get('evidence_mode')} | "
|
|
311
|
+
f"{detail} |"
|
|
312
|
+
)
|
|
313
|
+
rows.extend([
|
|
314
|
+
"",
|
|
315
|
+
"Source: " + ", ".join(f"`tests/certification/{name}`"
|
|
316
|
+
for name in sorted({name for name, _ in records})) + ".",
|
|
317
|
+
"Regenerate with `python scripts/probe-client-events.py`, which exits 0"
|
|
318
|
+
" when a client is absent because an unmeasured client is a normal"
|
|
319
|
+
" outcome rather than a failure.",
|
|
320
|
+
])
|
|
321
|
+
return rows
|
|
322
|
+
|
|
323
|
+
def support_matrix(bundle: dict) -> str:
|
|
324
|
+
labels = {
|
|
325
|
+
"claude-code-cli": "Claude Code CLI",
|
|
326
|
+
"codex-cli": "Codex CLI",
|
|
327
|
+
"github-copilot-cli": "GitHub Copilot CLI",
|
|
328
|
+
}
|
|
329
|
+
records = {item["client"]: item for item in bundle["records"]}
|
|
330
|
+
if set(records) != set(CLIENTS) or len(bundle["records"]) != len(CLIENTS):
|
|
331
|
+
raise ValueError("support matrix requires exactly the three clients")
|
|
332
|
+
lines = [
|
|
333
|
+
"<!-- Generated from certification evidence; do not edit. -->",
|
|
334
|
+
"# ADR Kit client support",
|
|
335
|
+
"",
|
|
336
|
+
"| Client | Surface | Windows | macOS | Linux | Evidence |",
|
|
337
|
+
"|---|---|---|---|---|---|",
|
|
338
|
+
]
|
|
339
|
+
for client in CLIENTS:
|
|
340
|
+
record = records[client]
|
|
341
|
+
status = "certified" if record["evidence_mode"] == "native" else "simulated only"
|
|
342
|
+
platforms = record["platforms"]
|
|
343
|
+
lines.append(
|
|
344
|
+
f"| {labels[client]} | CLI | {platforms['windows']['status']} | "
|
|
345
|
+
f"{platforms['macos']['status']} | {platforms['linux']['status']} | {status} |"
|
|
346
|
+
)
|
|
347
|
+
lines.extend(_lifecycle_rows(labels))
|
|
348
|
+
lines.extend(_probe_rows(labels))
|
|
349
|
+
lines.extend([
|
|
350
|
+
"",
|
|
351
|
+
"All retrieval is local, bounded, and index-first. Unsupported native lifecycle events are not advertised; deterministic pre-commit enforcement remains the backstop.",
|
|
352
|
+
])
|
|
353
|
+
lines.extend(_enforcement_rows(labels))
|
|
354
|
+
lines.extend(_degradation_rows(labels))
|
|
355
|
+
lines.extend([
|
|
356
|
+
"",
|
|
357
|
+
"IDE, cloud, preview, wrappers, legacy surfaces, and TASK-43 clients are not promoted by this matrix.",
|
|
358
|
+
"",
|
|
359
|
+
])
|
|
360
|
+
return "\n".join(lines)
|
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Plan and converge ADR Kit for detected Claude, Codex, and Copilot CLIs."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import argparse
|
|
7
|
+
import json
|
|
8
|
+
import subprocess
|
|
9
|
+
import sys
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import Mapping, Callable, Sequence
|
|
12
|
+
|
|
13
|
+
ROOT = Path(__file__).resolve().parent.parent
|
|
14
|
+
for import_root in (ROOT, ROOT / "scripts"):
|
|
15
|
+
if str(import_root) not in sys.path:
|
|
16
|
+
sys.path.insert(0, str(import_root))
|
|
17
|
+
|
|
18
|
+
from adr_settings import SettingsError, resolve_settings
|
|
19
|
+
from project_setup import apply_changes, plan_uninstall
|
|
20
|
+
from clients.installer.contracts import CLIENT_IDS
|
|
21
|
+
from clients.installer.detection import (
|
|
22
|
+
Client,
|
|
23
|
+
detect_client,
|
|
24
|
+
detect_clients,
|
|
25
|
+
detailed_detection,
|
|
26
|
+
sha256_file,
|
|
27
|
+
)
|
|
28
|
+
from clients.installer.native import (
|
|
29
|
+
INSTALLERS,
|
|
30
|
+
MARKETPLACES,
|
|
31
|
+
claude_marketplace_source_matches,
|
|
32
|
+
display_command,
|
|
33
|
+
install_claude,
|
|
34
|
+
install_codex,
|
|
35
|
+
install_copilot,
|
|
36
|
+
marketplace_source_matches,
|
|
37
|
+
restore_previous_install,
|
|
38
|
+
uninstall_client,
|
|
39
|
+
validate_install as _validate_install,
|
|
40
|
+
)
|
|
41
|
+
from clients.installer.payload import (
|
|
42
|
+
MIN_PYTHON,
|
|
43
|
+
PREPARED_MARKER,
|
|
44
|
+
REQUIRED_INSTALL_FILES,
|
|
45
|
+
default_install_root,
|
|
46
|
+
prepare_install_source,
|
|
47
|
+
payload_digest,
|
|
48
|
+
remove_owned_payloads,
|
|
49
|
+
validate_python as _validate_python,
|
|
50
|
+
validate_source,
|
|
51
|
+
)
|
|
52
|
+
from clients.installer.bounded import run_bounded
|
|
53
|
+
from clients.installer.judge_backend import record_host_client
|
|
54
|
+
from clients.installer.registrations import read_installed_versions
|
|
55
|
+
from clients.installer.smoke import validate_prepared_hooks, validate_prepared_mcp
|
|
56
|
+
from clients.installer.planning import build_plan, render_plan
|
|
57
|
+
from clients.installer.transaction import run_transaction
|
|
58
|
+
from clients.installer.updates import record_update_state, update_decision
|
|
59
|
+
SUPPORTED = CLIENT_IDS
|
|
60
|
+
Runner = Callable[[Sequence[str]], subprocess.CompletedProcess[str]]
|
|
61
|
+
def _run(command: Sequence[str]) -> subprocess.CompletedProcess[str]:
|
|
62
|
+
# Bounded: a client CLI is often a .CMD shim (TASK-171).
|
|
63
|
+
return run_bounded(
|
|
64
|
+
list(command), stdin=subprocess.DEVNULL, capture_output=True, text=True,
|
|
65
|
+
encoding="utf-8", errors="replace", timeout=120,
|
|
66
|
+
)
|
|
67
|
+
def _display_command(command: Sequence[str], system: str | None = None) -> str:
|
|
68
|
+
return display_command(command, system)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def validate_python(executable: str, runner: Runner = _run) -> str:
|
|
72
|
+
return _validate_python(executable, runner)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def validate_install(name: str, client: Client, runner: Runner = _run) -> None:
|
|
76
|
+
_validate_install(name, client, runner)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def report_migration_plan(source: Path, project_root: Path, runner: Runner = _run) -> None:
|
|
80
|
+
adr_dir = project_root / "docs" / "adr"
|
|
81
|
+
if not adr_dir.is_dir():
|
|
82
|
+
print(f"ADR format scan: no ADR directory at {adr_dir}; nothing to inspect.")
|
|
83
|
+
return
|
|
84
|
+
command = [sys.executable, str(source / "bin" / "adr-migrate"), "--plan", str(adr_dir)]
|
|
85
|
+
print(f"ADR format scan (read-only): {adr_dir}")
|
|
86
|
+
result = runner(command)
|
|
87
|
+
if result.returncode:
|
|
88
|
+
print(
|
|
89
|
+
" warning: format discovery could not complete; installation remains valid. "
|
|
90
|
+
+ (result.stderr or result.stdout).strip(),
|
|
91
|
+
file=sys.stderr,
|
|
92
|
+
)
|
|
93
|
+
elif result.stdout.strip():
|
|
94
|
+
for line in result.stdout.splitlines():
|
|
95
|
+
print(f" {line}")
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def parse_selection(raw: str, detected: dict[str, Client]) -> list[str]:
|
|
99
|
+
if raw == "auto":
|
|
100
|
+
return [name for name in SUPPORTED if name in detected]
|
|
101
|
+
if raw == "all":
|
|
102
|
+
missing = [name for name in SUPPORTED if name not in detected]
|
|
103
|
+
if missing:
|
|
104
|
+
raise ValueError("requested clients not detected: " + ", ".join(missing))
|
|
105
|
+
return list(SUPPORTED)
|
|
106
|
+
selected = [part.strip().lower() for part in raw.split(",") if part.strip()]
|
|
107
|
+
unknown = [name for name in selected if name not in SUPPORTED]
|
|
108
|
+
if unknown:
|
|
109
|
+
raise ValueError("unsupported clients: " + ", ".join(unknown))
|
|
110
|
+
missing = [name for name in selected if name not in detected]
|
|
111
|
+
if missing:
|
|
112
|
+
raise ValueError("requested clients not detected: " + ", ".join(missing))
|
|
113
|
+
return list(dict.fromkeys(selected))
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def install_selected_clients(
|
|
117
|
+
selected: Sequence[str],
|
|
118
|
+
detected: dict[str, Client],
|
|
119
|
+
source: Path,
|
|
120
|
+
*,
|
|
121
|
+
version: str,
|
|
122
|
+
dry_run: bool,
|
|
123
|
+
skip_validation: bool,
|
|
124
|
+
runner: Runner = _run,
|
|
125
|
+
installed_versions: Mapping[str, str | None] | None = None,
|
|
126
|
+
) -> tuple[list[str], list[tuple[str, str]]]:
|
|
127
|
+
installed, failures = [], []
|
|
128
|
+
for name in selected:
|
|
129
|
+
print(f"Installing ADR Kit for {name}:")
|
|
130
|
+
try:
|
|
131
|
+
def apply() -> None:
|
|
132
|
+
INSTALLERS[name](
|
|
133
|
+
detected[name], source, dry_run, runner, desired_version=version
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
def validate() -> None:
|
|
137
|
+
if not dry_run and not skip_validation:
|
|
138
|
+
validate_install(name, detected[name], runner)
|
|
139
|
+
|
|
140
|
+
def rollback() -> None:
|
|
141
|
+
restore_previous_install(
|
|
142
|
+
name, detected[name], source, runner,
|
|
143
|
+
had_plugin=(installed_versions or {}).get(name) is not None,
|
|
144
|
+
marker_name=PREPARED_MARKER,
|
|
145
|
+
)
|
|
146
|
+
|
|
147
|
+
if dry_run:
|
|
148
|
+
apply()
|
|
149
|
+
else:
|
|
150
|
+
run_transaction(
|
|
151
|
+
name, state_root=source.parent.parent / "state",
|
|
152
|
+
apply=apply, validate=validate, rollback=rollback,
|
|
153
|
+
)
|
|
154
|
+
installed.append(name)
|
|
155
|
+
except (OSError, RuntimeError, subprocess.SubprocessError) as exc:
|
|
156
|
+
failures.append((name, str(exc)))
|
|
157
|
+
print(f" FAILED ({name}): {exc}", file=sys.stderr)
|
|
158
|
+
return installed, failures
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def _parser() -> argparse.ArgumentParser:
|
|
162
|
+
parser = argparse.ArgumentParser(
|
|
163
|
+
description="Install ADR Kit for detected Claude Code, Codex, and Copilot CLIs."
|
|
164
|
+
)
|
|
165
|
+
parser.add_argument("--clients", "--agents", default="auto")
|
|
166
|
+
parser.add_argument("--source", type=Path, default=ROOT)
|
|
167
|
+
parser.add_argument("--project-root", type=Path, default=Path.cwd())
|
|
168
|
+
parser.add_argument("--python", default=sys.executable)
|
|
169
|
+
parser.add_argument("--install-root", type=Path)
|
|
170
|
+
parser.add_argument("--global-settings", type=Path)
|
|
171
|
+
parser.add_argument("--format", choices=("human", "json"), default="human")
|
|
172
|
+
parser.add_argument("--dry-run", action="store_true")
|
|
173
|
+
parser.add_argument("--plan", action="store_true")
|
|
174
|
+
parser.add_argument("--yes", action="store_true")
|
|
175
|
+
parser.add_argument("--skip-validation", action="store_true")
|
|
176
|
+
parser.add_argument("--detect-only", action="store_true")
|
|
177
|
+
parser.add_argument("--uninstall", action="store_true")
|
|
178
|
+
return parser
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
182
|
+
parser, args = _parser(), _parser().parse_args(argv)
|
|
183
|
+
source, project_root = args.source.expanduser().resolve(), args.project_root.expanduser().resolve()
|
|
184
|
+
if not source.is_dir():
|
|
185
|
+
parser.error(f"source is not a directory: {source}")
|
|
186
|
+
try:
|
|
187
|
+
version = validate_source(source)
|
|
188
|
+
python_executable = validate_python(args.python)
|
|
189
|
+
resolved = resolve_settings(project_root, global_path=args.global_settings)
|
|
190
|
+
except (RuntimeError, SettingsError) as exc:
|
|
191
|
+
parser.error(str(exc))
|
|
192
|
+
detected = detect_clients()
|
|
193
|
+
update = update_decision(resolved["values"], version)
|
|
194
|
+
if resolved["values"]["update"]["policy"] == "pinned":
|
|
195
|
+
pinned = resolved["values"]["update"]["pinned_version"]
|
|
196
|
+
if pinned != version:
|
|
197
|
+
parser.error(f"local payload {version} does not match pinned version {pinned!r}")
|
|
198
|
+
install_root = args.install_root.expanduser().resolve() if args.install_root else default_install_root()
|
|
199
|
+
detailed = detailed_detection(
|
|
200
|
+
detected,
|
|
201
|
+
install_root=install_root,
|
|
202
|
+
effective_settings=resolved["values"],
|
|
203
|
+
installed_versions=read_installed_versions(detected, runner=_run),
|
|
204
|
+
)
|
|
205
|
+
identity = {
|
|
206
|
+
"version": version,
|
|
207
|
+
"source": str(source),
|
|
208
|
+
"source_sha256": sha256_file(source / ".claude-plugin" / "plugin.json"),
|
|
209
|
+
"payload_sha256": payload_digest(source),
|
|
210
|
+
"update": update,
|
|
211
|
+
}
|
|
212
|
+
if args.detect_only:
|
|
213
|
+
payload = {
|
|
214
|
+
"schema_version": 1, "adr_kit": identity,
|
|
215
|
+
"clients": {
|
|
216
|
+
name: detailed[name].as_dict() if name in detailed else None
|
|
217
|
+
for name in SUPPORTED
|
|
218
|
+
},
|
|
219
|
+
}
|
|
220
|
+
if args.format == "json":
|
|
221
|
+
print(json.dumps(payload, indent=2, sort_keys=True))
|
|
222
|
+
else:
|
|
223
|
+
for name in SUPPORTED:
|
|
224
|
+
state = detailed.get(name)
|
|
225
|
+
print(f"{name}: {state.executable} ({state.version})" if state else f"{name}: not detected")
|
|
226
|
+
return 0
|
|
227
|
+
try:
|
|
228
|
+
selected = parse_selection(args.clients, detected)
|
|
229
|
+
except ValueError as exc:
|
|
230
|
+
parser.error(str(exc))
|
|
231
|
+
selected = [
|
|
232
|
+
name for name in selected
|
|
233
|
+
if resolved["values"]["clients"][name]["enabled"] is not False
|
|
234
|
+
]
|
|
235
|
+
plan = build_plan(
|
|
236
|
+
detailed, source=source, version=version,
|
|
237
|
+
source_sha256=identity["source_sha256"] or "",
|
|
238
|
+
effective_settings=resolved["values"],
|
|
239
|
+
requested=tuple(selected) if args.clients != "auto" else None,
|
|
240
|
+
remove=args.uninstall,
|
|
241
|
+
)
|
|
242
|
+
print(render_plan(plan, format=args.format))
|
|
243
|
+
if args.plan:
|
|
244
|
+
return 0
|
|
245
|
+
if plan.requires_confirmation and not args.yes:
|
|
246
|
+
parser.error("breaking-version migration requires --yes after reviewing --plan")
|
|
247
|
+
if not selected:
|
|
248
|
+
print("No supported CLI detected; nothing installed.", file=sys.stderr)
|
|
249
|
+
return 2
|
|
250
|
+
if args.uninstall:
|
|
251
|
+
failures = []
|
|
252
|
+
for name in selected:
|
|
253
|
+
try:
|
|
254
|
+
uninstall_client(detected[name], dry_run=args.dry_run, runner=_run)
|
|
255
|
+
except RuntimeError as exc:
|
|
256
|
+
failures.append((name, str(exc)))
|
|
257
|
+
if not failures and not args.dry_run:
|
|
258
|
+
remove_owned_payloads(install_root)
|
|
259
|
+
apply_changes(
|
|
260
|
+
project_root, plan_uninstall(project_root, selected),
|
|
261
|
+
configure_hooks_path=False,
|
|
262
|
+
)
|
|
263
|
+
return 1 if failures else 0
|
|
264
|
+
try:
|
|
265
|
+
prepared = prepare_install_source(
|
|
266
|
+
source, version=version, python_executable=python_executable,
|
|
267
|
+
install_root=install_root, dry_run=args.dry_run,
|
|
268
|
+
)
|
|
269
|
+
if not args.dry_run:
|
|
270
|
+
validate_prepared_mcp(prepared, python_executable)
|
|
271
|
+
validate_prepared_hooks(prepared)
|
|
272
|
+
except RuntimeError as exc:
|
|
273
|
+
parser.error(str(exc))
|
|
274
|
+
installed, failures = install_selected_clients(
|
|
275
|
+
selected, detected, prepared, version=version, dry_run=args.dry_run,
|
|
276
|
+
skip_validation=args.skip_validation,
|
|
277
|
+
installed_versions={n: c.installed_version for n, c in detailed.items()},
|
|
278
|
+
)
|
|
279
|
+
report_migration_plan(source, project_root)
|
|
280
|
+
record_host_client(
|
|
281
|
+
source, project_root, installed, runner=_run, dry_run=args.dry_run
|
|
282
|
+
)
|
|
283
|
+
if installed:
|
|
284
|
+
for name in installed:
|
|
285
|
+
record_update_state(
|
|
286
|
+
install_root.parent, name, version=version, trigger=update["trigger"]
|
|
287
|
+
)
|
|
288
|
+
print("ADR Kit install complete for: " + ", ".join(installed))
|
|
289
|
+
if failures:
|
|
290
|
+
print(
|
|
291
|
+
"ADR Kit install failures: "
|
|
292
|
+
+ "; ".join(f"{name}: {detail}" for name, detail in failures),
|
|
293
|
+
file=sys.stderr,
|
|
294
|
+
)
|
|
295
|
+
return 1
|
|
296
|
+
return 0
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
if __name__ == "__main__":
|
|
300
|
+
raise SystemExit(main())
|