@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,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())