@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,280 @@
|
|
|
1
|
+
"""Shared, stdlib-only validation for adr-kit project configuration."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import re
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import Any, Dict, List
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class ConfigValidationError(ValueError):
|
|
12
|
+
"""Raised when .adr-kit.json is malformed or violates its schema."""
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
# Keys the schema once declared and no code ever read. Removing them outright
|
|
16
|
+
# would fail every existing config that sets one, so they are accepted and
|
|
17
|
+
# ignored instead: the value never took effect, and breaking the file over a
|
|
18
|
+
# setting that was already inert would be a worse trade than a warning.
|
|
19
|
+
# A caller that wants to surface them uses retired_keys_present().
|
|
20
|
+
RETIRED_KEYS: Dict[str, str] = {
|
|
21
|
+
"$.judge.llm_timeout_ms": (
|
|
22
|
+
"never read; judge.llm_timeout_seconds is the timeout that applies"
|
|
23
|
+
),
|
|
24
|
+
"$.judge.pre_push_timeout_ms": (
|
|
25
|
+
"never read; adr-kit ships no pre-push hook for it to bound"
|
|
26
|
+
),
|
|
27
|
+
"$.policy.regex_compile_checks": (
|
|
28
|
+
"never read; adr-lint always compiles Enforcement patterns"
|
|
29
|
+
),
|
|
30
|
+
"$.policy.pattern_warnings": (
|
|
31
|
+
"never read; adr-lint always emits anti-pattern advisories"
|
|
32
|
+
),
|
|
33
|
+
"$.context.weights": (
|
|
34
|
+
"never read; the index-first scorer replaced weighted signals in v0.40.0"
|
|
35
|
+
),
|
|
36
|
+
"$.context.weights.exact_keyword": "part of the retired context.weights block",
|
|
37
|
+
"$.context.weights.domain_tag": "part of the retired context.weights block",
|
|
38
|
+
"$.context.weights.related_decisions": (
|
|
39
|
+
"part of the retired context.weights block"
|
|
40
|
+
),
|
|
41
|
+
"$.context.weights.acceptance_status": (
|
|
42
|
+
"part of the retired context.weights block"
|
|
43
|
+
),
|
|
44
|
+
"$.context.weights.recency": "part of the retired context.weights block",
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
# Keys that DID something and no longer do (ADR-036). Unlike RETIRED_KEYS,
|
|
48
|
+
# these are refused rather than ignored: a config naming one made a real
|
|
49
|
+
# choice once - a backend, a model, a command - and silently dropping that
|
|
50
|
+
# choice would be the exact drift the kit exists to prevent. Each entry is
|
|
51
|
+
# the sentence "unknown property" cannot say: what replaced the key.
|
|
52
|
+
REMOVED_KEYS: Dict[str, str] = {
|
|
53
|
+
"$.judge.openrouter_model": (
|
|
54
|
+
"the openrouter backend was retired by ADR-036; the judge runs on the "
|
|
55
|
+
"host client's own model. Remove the key; operators can override per "
|
|
56
|
+
"run with ADR_KIT_LLM_CMD / --llm-cmd."
|
|
57
|
+
),
|
|
58
|
+
"$.judge.ollama_model": (
|
|
59
|
+
"the ollama backend was retired by ADR-036; the judge runs on the "
|
|
60
|
+
"host client's own model. Remove the key; operators can override per "
|
|
61
|
+
"run with ADR_KIT_LLM_CMD / --llm-cmd."
|
|
62
|
+
),
|
|
63
|
+
"$.judge.openai_model": (
|
|
64
|
+
"the openai-compatible backend was retired by ADR-036; the judge runs "
|
|
65
|
+
"on the host client's own model. Remove the key; operators can "
|
|
66
|
+
"override per run with ADR_KIT_LLM_CMD / --llm-cmd."
|
|
67
|
+
),
|
|
68
|
+
"$.judge.llm_cmd": (
|
|
69
|
+
"ignored since ADR-017 and removed by ADR-036: repository-tracked "
|
|
70
|
+
"configuration may never supply a command. Remove the key; operators "
|
|
71
|
+
"use ADR_KIT_LLM_CMD / --llm-cmd."
|
|
72
|
+
),
|
|
73
|
+
"$.judge.llm_model": (
|
|
74
|
+
"ignored since ADR-017 and removed by ADR-036: the host backend "
|
|
75
|
+
"passes no model flag, so each CLI resolves the model its own user "
|
|
76
|
+
"configured. Remove the key."
|
|
77
|
+
),
|
|
78
|
+
"$.judge.llm_default": (
|
|
79
|
+
"removed by ADR-036; judge.llm_enabled is the per-commit switch. "
|
|
80
|
+
"Remove the key."
|
|
81
|
+
),
|
|
82
|
+
"$.suggest.llm_cmd": (
|
|
83
|
+
"ignored since ADR-017 and removed by ADR-036: repository-tracked "
|
|
84
|
+
"configuration may never supply a command. Remove the key; operators "
|
|
85
|
+
"use ADR_KIT_LLM_CMD / --llm-cmd."
|
|
86
|
+
),
|
|
87
|
+
"$.suggest.llm_model": (
|
|
88
|
+
"ignored since ADR-017 and removed by ADR-036: adr-suggest resolves "
|
|
89
|
+
"the same host backend as the judge. Remove the key."
|
|
90
|
+
),
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def retired_keys_present(config: Any) -> List[str]:
|
|
95
|
+
"""Return the dotted paths of retired keys this config still sets.
|
|
96
|
+
|
|
97
|
+
Callers print these as a warning. The values are inert either way.
|
|
98
|
+
"""
|
|
99
|
+
found: List[str] = []
|
|
100
|
+
|
|
101
|
+
def walk(value: Any, path: str) -> None:
|
|
102
|
+
if not isinstance(value, dict):
|
|
103
|
+
return
|
|
104
|
+
for key, item in value.items():
|
|
105
|
+
child = _path(path, str(key))
|
|
106
|
+
if child in RETIRED_KEYS:
|
|
107
|
+
found.append(child)
|
|
108
|
+
continue
|
|
109
|
+
walk(item, child)
|
|
110
|
+
|
|
111
|
+
walk(config, "$")
|
|
112
|
+
return sorted(found)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _type_matches(value: Any, expected: str) -> bool:
|
|
116
|
+
if expected == "object":
|
|
117
|
+
return isinstance(value, dict)
|
|
118
|
+
if expected == "array":
|
|
119
|
+
return isinstance(value, list)
|
|
120
|
+
if expected == "string":
|
|
121
|
+
return isinstance(value, str)
|
|
122
|
+
if expected == "boolean":
|
|
123
|
+
return isinstance(value, bool)
|
|
124
|
+
if expected == "integer":
|
|
125
|
+
return isinstance(value, int) and not isinstance(value, bool)
|
|
126
|
+
if expected == "number":
|
|
127
|
+
return isinstance(value, (int, float)) and not isinstance(value, bool)
|
|
128
|
+
if expected == "null":
|
|
129
|
+
return value is None
|
|
130
|
+
return True
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def _path(parent: str, key: str) -> str:
|
|
134
|
+
if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", key):
|
|
135
|
+
return f"{parent}.{key}"
|
|
136
|
+
return f"{parent}[{json.dumps(key, ensure_ascii=False)}]"
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def _validate(value: Any, schema: Dict[str, Any], path: str) -> List[str]:
|
|
140
|
+
issues: List[str] = []
|
|
141
|
+
|
|
142
|
+
if "oneOf" in schema:
|
|
143
|
+
matches = [
|
|
144
|
+
candidate
|
|
145
|
+
for candidate in schema["oneOf"]
|
|
146
|
+
if not _validate(value, candidate, path)
|
|
147
|
+
]
|
|
148
|
+
if len(matches) != 1:
|
|
149
|
+
issues.append(f"{path}: must match exactly one allowed schema")
|
|
150
|
+
return issues
|
|
151
|
+
|
|
152
|
+
expected = schema.get("type")
|
|
153
|
+
if isinstance(expected, str) and not _type_matches(value, expected):
|
|
154
|
+
issues.append(f"{path}: expected {expected}, got {type(value).__name__}")
|
|
155
|
+
return issues
|
|
156
|
+
|
|
157
|
+
if "enum" in schema and value not in schema["enum"]:
|
|
158
|
+
issues.append(
|
|
159
|
+
f"{path}: must be one of {', '.join(repr(item) for item in schema['enum'])}"
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
if isinstance(value, str):
|
|
163
|
+
min_length = schema.get("minLength")
|
|
164
|
+
if isinstance(min_length, int) and len(value) < min_length:
|
|
165
|
+
issues.append(f"{path}: must contain at least {min_length} character(s)")
|
|
166
|
+
pattern = schema.get("pattern")
|
|
167
|
+
if isinstance(pattern, str) and re.search(pattern, value) is None:
|
|
168
|
+
issues.append(f"{path}: does not match required pattern {pattern!r}")
|
|
169
|
+
|
|
170
|
+
if isinstance(value, list):
|
|
171
|
+
min_items = schema.get("minItems")
|
|
172
|
+
if isinstance(min_items, int) and len(value) < min_items:
|
|
173
|
+
issues.append(f"{path}: must contain at least {min_items} item(s)")
|
|
174
|
+
item_schema = schema.get("items")
|
|
175
|
+
if isinstance(item_schema, dict):
|
|
176
|
+
for index, item in enumerate(value):
|
|
177
|
+
issues.extend(_validate(item, item_schema, f"{path}[{index}]"))
|
|
178
|
+
|
|
179
|
+
if isinstance(value, (int, float)) and not isinstance(value, bool):
|
|
180
|
+
minimum = schema.get("minimum")
|
|
181
|
+
maximum = schema.get("maximum")
|
|
182
|
+
if isinstance(minimum, (int, float)) and value < minimum:
|
|
183
|
+
issues.append(f"{path}: must be >= {minimum}")
|
|
184
|
+
if isinstance(maximum, (int, float)) and value > maximum:
|
|
185
|
+
issues.append(f"{path}: must be <= {maximum}")
|
|
186
|
+
|
|
187
|
+
if isinstance(value, dict):
|
|
188
|
+
properties = schema.get("properties", {})
|
|
189
|
+
pattern_properties = schema.get("patternProperties", {})
|
|
190
|
+
required = schema.get("required", [])
|
|
191
|
+
for key in required:
|
|
192
|
+
if key not in value:
|
|
193
|
+
issues.append(f"{_path(path, key)}: required property is missing")
|
|
194
|
+
for key, item in value.items():
|
|
195
|
+
child_path = _path(path, str(key))
|
|
196
|
+
if key in properties:
|
|
197
|
+
issues.extend(_validate(item, properties[key], child_path))
|
|
198
|
+
continue
|
|
199
|
+
matching = [
|
|
200
|
+
child_schema
|
|
201
|
+
for pattern, child_schema in pattern_properties.items()
|
|
202
|
+
if re.search(pattern, str(key))
|
|
203
|
+
]
|
|
204
|
+
if matching:
|
|
205
|
+
for child_schema in matching:
|
|
206
|
+
issues.extend(_validate(item, child_schema, child_path))
|
|
207
|
+
continue
|
|
208
|
+
if child_path in RETIRED_KEYS:
|
|
209
|
+
continue
|
|
210
|
+
if child_path in REMOVED_KEYS:
|
|
211
|
+
issues.append(f"{child_path}: {REMOVED_KEYS[child_path]}")
|
|
212
|
+
continue
|
|
213
|
+
additional = schema.get("additionalProperties", True)
|
|
214
|
+
if additional is False:
|
|
215
|
+
issues.append(f"{child_path}: unknown property")
|
|
216
|
+
elif isinstance(additional, dict):
|
|
217
|
+
issues.extend(_validate(item, additional, child_path))
|
|
218
|
+
|
|
219
|
+
return issues
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
def validate_project_config(config: Any, schema_path: Path) -> Dict[str, Any]:
|
|
223
|
+
"""Validate config against the checked-in schema and return it as a dict."""
|
|
224
|
+
try:
|
|
225
|
+
schema = json.loads(schema_path.read_text(encoding="utf-8"))
|
|
226
|
+
except (OSError, json.JSONDecodeError) as exc:
|
|
227
|
+
raise ConfigValidationError(
|
|
228
|
+
f"cannot load configuration schema {schema_path}: {exc}"
|
|
229
|
+
) from exc
|
|
230
|
+
issues = _validate(config, schema, "$")
|
|
231
|
+
if issues:
|
|
232
|
+
raise ConfigValidationError("; ".join(issues))
|
|
233
|
+
return config
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
def load_project_config(path: Path, schema_path: Path) -> Dict[str, Any]:
|
|
237
|
+
"""Read and validate one .adr-kit.json file; missing files mean defaults."""
|
|
238
|
+
if not path.exists():
|
|
239
|
+
return {}
|
|
240
|
+
try:
|
|
241
|
+
config = json.loads(path.read_text(encoding="utf-8"))
|
|
242
|
+
except OSError as exc:
|
|
243
|
+
raise ConfigValidationError(f"cannot read {path}: {exc}") from exc
|
|
244
|
+
except json.JSONDecodeError as exc:
|
|
245
|
+
raise ConfigValidationError(
|
|
246
|
+
f"{path}: invalid JSON ({exc.msg} at line {exc.lineno})"
|
|
247
|
+
) from exc
|
|
248
|
+
try:
|
|
249
|
+
return validate_project_config(config, schema_path)
|
|
250
|
+
except ConfigValidationError as exc:
|
|
251
|
+
raise ConfigValidationError(f"{path}: schema validation failed: {exc}") from exc
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
DEFAULT_CONFIG_SCHEMA = (
|
|
255
|
+
Path(__file__).resolve().parent.parent / "schemas" / "adr-kit-config.schema.json"
|
|
256
|
+
)
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def load_validated_config(path: Path | None) -> Dict[str, Any]:
|
|
260
|
+
"""Read and schema-validate .adr-kit.json against the shipped schema.
|
|
261
|
+
|
|
262
|
+
Callers that need their own error type catch ConfigValidationError and
|
|
263
|
+
re-raise. A missing path or file yields defaults.
|
|
264
|
+
"""
|
|
265
|
+
if path is None:
|
|
266
|
+
return {}
|
|
267
|
+
return load_project_config(path, DEFAULT_CONFIG_SCHEMA)
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
def load_json_config(path: Path) -> Dict[str, Any]:
|
|
271
|
+
"""Read a JSON config object tolerantly; anything unusable yields {}.
|
|
272
|
+
|
|
273
|
+
The fail-open reader used by the advisory hook entry points, where a broken
|
|
274
|
+
config must never interrupt an edit or a session start.
|
|
275
|
+
"""
|
|
276
|
+
try:
|
|
277
|
+
data = json.loads(path.read_text(encoding="utf-8"))
|
|
278
|
+
except (OSError, json.JSONDecodeError):
|
|
279
|
+
return {}
|
|
280
|
+
return data if isinstance(data, dict) else {}
|
|
@@ -0,0 +1,407 @@
|
|
|
1
|
+
"""Fast client checks, bounded deep probes, and enumerated safe repairs."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
import shutil
|
|
7
|
+
import sys
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
from adr_doctor_models import check, client_root, generated_tree_owner
|
|
12
|
+
from adr_settings import (
|
|
13
|
+
SettingsError,
|
|
14
|
+
resolve_settings,
|
|
15
|
+
)
|
|
16
|
+
from clients.installer.contracts import CLIENT_IDS
|
|
17
|
+
from clients.installer.detection import detect_clients
|
|
18
|
+
# client_generation is deliberately NOT imported here. It is the generator's own
|
|
19
|
+
# source and is not mirrored into a client tree, so a module-scope import would
|
|
20
|
+
# kill bin/adr-doctor at import time in codex/ and copilot/ -- the same shape as
|
|
21
|
+
# the v0.44.1 outage. _generated_check imports it lazily, behind a check that a
|
|
22
|
+
# mirror never passes.
|
|
23
|
+
from project_setup import (
|
|
24
|
+
SetupError,
|
|
25
|
+
apply_changes,
|
|
26
|
+
collect_changes,
|
|
27
|
+
validate_markers,
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
HOOK_EVENTS = {
|
|
31
|
+
"claude": {
|
|
32
|
+
"SessionStart",
|
|
33
|
+
"UserPromptSubmit",
|
|
34
|
+
"PreToolUse",
|
|
35
|
+
"PostToolUse",
|
|
36
|
+
"SubagentStart",
|
|
37
|
+
"PreCompact",
|
|
38
|
+
},
|
|
39
|
+
"codex": {
|
|
40
|
+
"SessionStart",
|
|
41
|
+
"UserPromptSubmit",
|
|
42
|
+
"PreToolUse",
|
|
43
|
+
"PostToolUse",
|
|
44
|
+
"SubagentStart",
|
|
45
|
+
"PreCompact",
|
|
46
|
+
},
|
|
47
|
+
"copilot": {"sessionStart", "userPromptSubmitted", "postToolUse"},
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def resolve_launcher_target(
|
|
52
|
+
plugin_root: Path, command: str, args: list[str]
|
|
53
|
+
) -> tuple[str | None, list[str]]:
|
|
54
|
+
expanded = [
|
|
55
|
+
value.replace("${PLUGIN_ROOT}", str(plugin_root))
|
|
56
|
+
.replace("${CLAUDE_PLUGIN_ROOT}", str(plugin_root))
|
|
57
|
+
for value in args
|
|
58
|
+
]
|
|
59
|
+
command_path = Path(command).expanduser()
|
|
60
|
+
resolved_command = (
|
|
61
|
+
str(command_path.resolve())
|
|
62
|
+
if command_path.is_absolute()
|
|
63
|
+
else shutil.which(command)
|
|
64
|
+
)
|
|
65
|
+
targets = []
|
|
66
|
+
for value in expanded:
|
|
67
|
+
candidate = Path(value)
|
|
68
|
+
if not candidate.is_absolute() and value.startswith("."):
|
|
69
|
+
candidate = plugin_root / candidate
|
|
70
|
+
if candidate.suffix in {"", ".py", ".cmd", ".sh"} and (
|
|
71
|
+
"/" in value or "\\" in value
|
|
72
|
+
):
|
|
73
|
+
targets.append(str(candidate.resolve()))
|
|
74
|
+
return resolved_command, targets
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def check_mcp_launcher(
|
|
78
|
+
plugin_root: Path, client: str, *, required: bool
|
|
79
|
+
) -> dict[str, Any]:
|
|
80
|
+
root = client_root(plugin_root, client)
|
|
81
|
+
if root is None:
|
|
82
|
+
return check(
|
|
83
|
+
"mcp-launcher", client=client, status="unsupported", required=False,
|
|
84
|
+
summary=f"{client} is not installed in this generated client tree",
|
|
85
|
+
)
|
|
86
|
+
config_path = root / ".mcp.json"
|
|
87
|
+
if not config_path.is_file():
|
|
88
|
+
return check(
|
|
89
|
+
"mcp-launcher", client=client, status="failed", required=required,
|
|
90
|
+
summary=f"missing owned MCP manifest {config_path}",
|
|
91
|
+
actions=[{"detail": f"Reinstall ADR Kit for {client}."}],
|
|
92
|
+
)
|
|
93
|
+
try:
|
|
94
|
+
server = json.loads(config_path.read_text(encoding="utf-8"))[
|
|
95
|
+
"mcpServers"
|
|
96
|
+
]["adr-kit"]
|
|
97
|
+
command, args = server["command"], server["args"]
|
|
98
|
+
if not isinstance(command, str) or not isinstance(args, list):
|
|
99
|
+
raise TypeError("command/args")
|
|
100
|
+
except (OSError, UnicodeError, json.JSONDecodeError, KeyError, TypeError) as exc:
|
|
101
|
+
return check(
|
|
102
|
+
"mcp-launcher", client=client, status="failed", required=required,
|
|
103
|
+
summary=f"invalid owned MCP manifest {config_path}: {exc}",
|
|
104
|
+
actions=[{"detail": f"Reinstall ADR Kit for {client}."}],
|
|
105
|
+
)
|
|
106
|
+
resolved, targets = resolve_launcher_target(root, command, args)
|
|
107
|
+
missing = [target for target in targets if not Path(target).is_file()]
|
|
108
|
+
if resolved is None or missing:
|
|
109
|
+
return check(
|
|
110
|
+
"mcp-launcher", client=client, status="stale", required=required,
|
|
111
|
+
summary="MCP launcher resolves to a missing command or removed payload",
|
|
112
|
+
evidence=[
|
|
113
|
+
{
|
|
114
|
+
"path": str(config_path),
|
|
115
|
+
"command": command,
|
|
116
|
+
"resolved_command": resolved,
|
|
117
|
+
"missing_targets": missing,
|
|
118
|
+
}
|
|
119
|
+
],
|
|
120
|
+
actions=[
|
|
121
|
+
{
|
|
122
|
+
"command": (
|
|
123
|
+
f"{sys.executable} scripts/install-agent-envs.py "
|
|
124
|
+
f"--clients {client}"
|
|
125
|
+
)
|
|
126
|
+
}
|
|
127
|
+
],
|
|
128
|
+
)
|
|
129
|
+
return check(
|
|
130
|
+
"mcp-launcher", client=client, status="healthy", required=required,
|
|
131
|
+
summary="MCP command and payload target resolve",
|
|
132
|
+
evidence=[
|
|
133
|
+
{
|
|
134
|
+
"path": str(config_path),
|
|
135
|
+
"resolved_command": resolved,
|
|
136
|
+
"targets": targets,
|
|
137
|
+
}
|
|
138
|
+
],
|
|
139
|
+
)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def check_hook_package(plugin_root: Path, client: str) -> dict[str, Any]:
|
|
143
|
+
root = client_root(plugin_root, client)
|
|
144
|
+
if root is None:
|
|
145
|
+
return check(
|
|
146
|
+
"hook-package", client=client, status="unsupported", required=False,
|
|
147
|
+
summary=f"{client} is not installed in this generated client tree",
|
|
148
|
+
)
|
|
149
|
+
config_path = (
|
|
150
|
+
root / "hooks" / "hooks.json"
|
|
151
|
+
if client != "copilot"
|
|
152
|
+
else root / "hooks.json"
|
|
153
|
+
)
|
|
154
|
+
try:
|
|
155
|
+
payload = json.loads(config_path.read_text(encoding="utf-8"))
|
|
156
|
+
hooks = payload["hooks"]
|
|
157
|
+
if not isinstance(hooks, dict) or set(hooks) != HOOK_EVENTS[client]:
|
|
158
|
+
raise ValueError("event set differs from the certified contract")
|
|
159
|
+
handlers = [
|
|
160
|
+
handler
|
|
161
|
+
for groups in hooks.values()
|
|
162
|
+
for group in groups
|
|
163
|
+
for handler in (
|
|
164
|
+
group.get("hooks", []) if client != "copilot" else [group]
|
|
165
|
+
)
|
|
166
|
+
]
|
|
167
|
+
if not handlers:
|
|
168
|
+
raise ValueError("no command handlers")
|
|
169
|
+
if client == "copilot":
|
|
170
|
+
if any(
|
|
171
|
+
not isinstance(handler.get("bash"), str)
|
|
172
|
+
or not isinstance(handler.get("powershell"), str)
|
|
173
|
+
for handler in handlers
|
|
174
|
+
):
|
|
175
|
+
raise ValueError("missing bash or PowerShell command")
|
|
176
|
+
elif any(handler.get("type") != "command" for handler in handlers):
|
|
177
|
+
raise ValueError("non-command handler")
|
|
178
|
+
except (
|
|
179
|
+
OSError,
|
|
180
|
+
UnicodeError,
|
|
181
|
+
json.JSONDecodeError,
|
|
182
|
+
KeyError,
|
|
183
|
+
TypeError,
|
|
184
|
+
ValueError,
|
|
185
|
+
) as exc:
|
|
186
|
+
return check(
|
|
187
|
+
"hook-package",
|
|
188
|
+
client=client,
|
|
189
|
+
status="failed",
|
|
190
|
+
required=False,
|
|
191
|
+
summary=f"broken native hook package: {config_path}: {exc}",
|
|
192
|
+
actions=[{"detail": f"Reinstall ADR Kit for {client}."}],
|
|
193
|
+
)
|
|
194
|
+
runtime = root / "hooks" / "adr-hook.py"
|
|
195
|
+
native = root / "hooks" / "bin" / "windows-x64" / "adr-hook.exe"
|
|
196
|
+
wrapper = root / "hooks" / "run-hook.cmd"
|
|
197
|
+
required_files = [runtime, native]
|
|
198
|
+
if client != "copilot":
|
|
199
|
+
required_files.append(wrapper)
|
|
200
|
+
missing = [str(path) for path in required_files if not path.is_file()]
|
|
201
|
+
if missing:
|
|
202
|
+
return check(
|
|
203
|
+
"hook-package",
|
|
204
|
+
client=client,
|
|
205
|
+
status="failed",
|
|
206
|
+
required=False,
|
|
207
|
+
summary="native hook config points at a missing runtime",
|
|
208
|
+
evidence=[{"missing": missing}],
|
|
209
|
+
actions=[{"detail": f"Reinstall ADR Kit for {client}."}],
|
|
210
|
+
)
|
|
211
|
+
return check(
|
|
212
|
+
"hook-package",
|
|
213
|
+
client=client,
|
|
214
|
+
status="healthy",
|
|
215
|
+
required=False,
|
|
216
|
+
summary="native hook shape and Windows/POSIX launchers resolve",
|
|
217
|
+
evidence=[{"path": str(config_path), "events": sorted(hooks)}],
|
|
218
|
+
)
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def _generated_check(plugin_root: Path, check_only: bool) -> tuple[dict, list[dict]]:
|
|
222
|
+
# A generated tree holds no canonical inputs to diff against, so there is
|
|
223
|
+
# nothing here to be stale. Returning before the import matters twice: the
|
|
224
|
+
# generator's source is not mirrored, and in repair mode generate() would
|
|
225
|
+
# otherwise write into the very tree it is inspecting.
|
|
226
|
+
if generated_tree_owner(plugin_root) is not None:
|
|
227
|
+
return check(
|
|
228
|
+
"generated-adapters", status="unsupported", required=False,
|
|
229
|
+
summary="generated client tree carries no canonical inputs to diff",
|
|
230
|
+
actions=[{
|
|
231
|
+
"detail": (
|
|
232
|
+
"Run adr-doctor from the ADR Kit payload root to check "
|
|
233
|
+
"adapter drift."
|
|
234
|
+
)
|
|
235
|
+
}],
|
|
236
|
+
), []
|
|
237
|
+
from client_generation import GenerationError, generate # not mirrored
|
|
238
|
+
try:
|
|
239
|
+
_stats, drift = generate(plugin_root, check=True)
|
|
240
|
+
except (GenerationError, OSError) as exc:
|
|
241
|
+
return check(
|
|
242
|
+
"generated-adapters", status="failed",
|
|
243
|
+
summary=f"generated artifact check failed: {exc}",
|
|
244
|
+
), []
|
|
245
|
+
if not drift:
|
|
246
|
+
return check(
|
|
247
|
+
"generated-adapters", status="healthy",
|
|
248
|
+
summary="generated client artifacts match canonical inputs",
|
|
249
|
+
), []
|
|
250
|
+
if check_only:
|
|
251
|
+
return check(
|
|
252
|
+
"generated-adapters", status="stale",
|
|
253
|
+
summary="generated client artifacts drifted",
|
|
254
|
+
actions=[{
|
|
255
|
+
"command": (
|
|
256
|
+
f"{sys.executable} "
|
|
257
|
+
f"{plugin_root / 'scripts' / 'build-client-adapters.py'}"
|
|
258
|
+
)
|
|
259
|
+
}],
|
|
260
|
+
), []
|
|
261
|
+
try:
|
|
262
|
+
generate(plugin_root, check=False)
|
|
263
|
+
except (GenerationError, OSError) as exc:
|
|
264
|
+
return check(
|
|
265
|
+
"generated-adapters", status="failed",
|
|
266
|
+
summary=f"safe regeneration failed: {exc}",
|
|
267
|
+
), []
|
|
268
|
+
evidence = {"kind": "generated-adapters", "path": str(plugin_root)}
|
|
269
|
+
return check(
|
|
270
|
+
"generated-adapters", status="repaired",
|
|
271
|
+
summary="regenerated owned client artifacts",
|
|
272
|
+
repairs=[evidence],
|
|
273
|
+
), [evidence]
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def _guidance_check(root: Path) -> dict:
|
|
277
|
+
guide = root / ".adr-kit" / "ADR-guide.md"
|
|
278
|
+
problems = []
|
|
279
|
+
for relative in ("AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md"):
|
|
280
|
+
path = root / relative
|
|
281
|
+
if not path.is_file():
|
|
282
|
+
continue
|
|
283
|
+
try:
|
|
284
|
+
validate_markers(path.read_text(encoding="utf-8-sig"), path)
|
|
285
|
+
except (OSError, UnicodeError, SetupError) as exc:
|
|
286
|
+
problems.append(str(exc))
|
|
287
|
+
if problems:
|
|
288
|
+
return check(
|
|
289
|
+
"project-guidance", status="failed",
|
|
290
|
+
summary="managed instruction markers are malformed",
|
|
291
|
+
evidence=[{"problems": problems}],
|
|
292
|
+
actions=[{"command": "python scripts/setup-project.py --dry-run"}],
|
|
293
|
+
)
|
|
294
|
+
if not guide.is_file():
|
|
295
|
+
return check(
|
|
296
|
+
"project-guidance", status="degraded", required=False,
|
|
297
|
+
summary="project has no generated ADR guide",
|
|
298
|
+
actions=[{"command": "python scripts/setup-project.py"}],
|
|
299
|
+
)
|
|
300
|
+
return check(
|
|
301
|
+
"project-guidance", status="healthy",
|
|
302
|
+
summary="guide and managed instruction markers are structurally valid",
|
|
303
|
+
evidence=[{"path": str(guide)}],
|
|
304
|
+
)
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
def run_client_checks(
|
|
308
|
+
root: Path,
|
|
309
|
+
plugin_root: Path,
|
|
310
|
+
*,
|
|
311
|
+
global_settings: Path | None,
|
|
312
|
+
check_only: bool,
|
|
313
|
+
allow_fix: bool,
|
|
314
|
+
) -> tuple[list[dict], list[dict]]:
|
|
315
|
+
checks, repairs = [], []
|
|
316
|
+
generated, generated_repairs = _generated_check(plugin_root, check_only)
|
|
317
|
+
checks.append(generated)
|
|
318
|
+
repairs.extend(generated_repairs)
|
|
319
|
+
try:
|
|
320
|
+
settings = resolve_settings(root, global_path=global_settings)["values"]
|
|
321
|
+
checks.append(check(
|
|
322
|
+
"settings", status="healthy",
|
|
323
|
+
summary="global/project settings parsed with known keys",
|
|
324
|
+
))
|
|
325
|
+
except SettingsError as exc:
|
|
326
|
+
settings = None
|
|
327
|
+
checks.append(check(
|
|
328
|
+
"settings", status="failed", summary=str(exc),
|
|
329
|
+
actions=[{"detail": "Correct the named ADR Kit settings file."}],
|
|
330
|
+
))
|
|
331
|
+
guidance = _guidance_check(root)
|
|
332
|
+
checks.append(guidance)
|
|
333
|
+
integration_required = (root / ".adr-kit" / "ADR-guide.md").is_file()
|
|
334
|
+
detected = detect_clients()
|
|
335
|
+
for name in CLIENT_IDS:
|
|
336
|
+
enabled = settings["clients"][name]["enabled"] if settings else None
|
|
337
|
+
if enabled is False:
|
|
338
|
+
checks.append(check(
|
|
339
|
+
"native-client", client=name, status="disabled", required=False,
|
|
340
|
+
summary="client disabled by effective settings",
|
|
341
|
+
))
|
|
342
|
+
continue
|
|
343
|
+
client = detected.get(name)
|
|
344
|
+
checks.append(check(
|
|
345
|
+
"native-client", client=name,
|
|
346
|
+
status="healthy" if client else "unsupported",
|
|
347
|
+
required=False,
|
|
348
|
+
summary=(
|
|
349
|
+
f"detected {client.version} at {client.executable}"
|
|
350
|
+
if client else "native CLI not installed"
|
|
351
|
+
),
|
|
352
|
+
evidence=[{"version": client.version, "path": client.executable}] if client else [],
|
|
353
|
+
))
|
|
354
|
+
checks.append(
|
|
355
|
+
check_mcp_launcher(
|
|
356
|
+
plugin_root, name, required=integration_required
|
|
357
|
+
)
|
|
358
|
+
)
|
|
359
|
+
checks.append(check_hook_package(plugin_root, name))
|
|
360
|
+
if allow_fix and guidance["status"] in {
|
|
361
|
+
"degraded",
|
|
362
|
+
"failed",
|
|
363
|
+
}:
|
|
364
|
+
selected = [
|
|
365
|
+
name for name in CLIENT_IDS
|
|
366
|
+
if name in detected
|
|
367
|
+
and settings
|
|
368
|
+
and settings["clients"][name]["enabled"] is not False
|
|
369
|
+
]
|
|
370
|
+
try:
|
|
371
|
+
changes, configure = collect_changes(
|
|
372
|
+
root,
|
|
373
|
+
plugin_root,
|
|
374
|
+
selected,
|
|
375
|
+
pre_commit_enabled=bool(
|
|
376
|
+
settings and settings["pre_commit"]["enabled"]
|
|
377
|
+
),
|
|
378
|
+
)
|
|
379
|
+
apply_changes(root, changes, configure_hooks_path=configure)
|
|
380
|
+
for change in changes:
|
|
381
|
+
repair = {
|
|
382
|
+
"kind": change.action,
|
|
383
|
+
"path": str(change.path),
|
|
384
|
+
}
|
|
385
|
+
repairs.append(repair)
|
|
386
|
+
if changes:
|
|
387
|
+
checks.append(check(
|
|
388
|
+
"project-guidance-fix",
|
|
389
|
+
status="repaired",
|
|
390
|
+
summary="backed up and converged ADR Kit-owned project guidance",
|
|
391
|
+
repairs=repairs[-len(changes):],
|
|
392
|
+
actions=[
|
|
393
|
+
{
|
|
394
|
+
"detail": (
|
|
395
|
+
f"Restore backups under "
|
|
396
|
+
f"{root / '.adr-kit' / 'backups'} if needed."
|
|
397
|
+
)
|
|
398
|
+
}
|
|
399
|
+
],
|
|
400
|
+
))
|
|
401
|
+
except SetupError as exc:
|
|
402
|
+
checks.append(check(
|
|
403
|
+
"project-guidance-fix",
|
|
404
|
+
status="failed",
|
|
405
|
+
summary=f"managed repair stopped safely: {exc}",
|
|
406
|
+
))
|
|
407
|
+
return checks, repairs
|