@elvis1513/auto-coding-skill 4.2.8 → 4.3.1
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/README.md +110 -7
- package/cli/assets/managed-install.json +1 -1
- package/cli/assets/skill/SKILL.md +7 -7
- package/cli/assets/skill/data/policies/feedback-resolutions-v1.json +15 -0
- package/cli/assets/skill/data/policies/workflow-migrations-v1.json +2 -2
- package/cli/assets/skill/data/templates/ENGINEERING.md +17 -12
- package/cli/assets/skill/data/templates/bridges/AGENTS.md +14 -8
- package/cli/assets/skill/scripts/ap.py +3094 -641
- package/cli/assets/skill/scripts/core.py +363 -1
- package/cli/assets/skill/scripts/install_integrity.py +12 -10
- package/cli/assets/skill/scripts/scaffold_templates.py +146 -0
- package/cli/src/index.js +1188 -317
- package/cli/tests/ap_concurrency_test.py +1 -1
- package/cli/tests/ap_profiles_test.py +98 -33
- package/cli/tests/core_shell_test.py +261 -0
- package/cli/tests/index.test.js +1694 -180
- package/package.json +1 -1
|
@@ -11,6 +11,7 @@ import contextlib
|
|
|
11
11
|
import hashlib
|
|
12
12
|
import datetime as _dt
|
|
13
13
|
import fnmatch
|
|
14
|
+
import hmac
|
|
14
15
|
import io
|
|
15
16
|
import json
|
|
16
17
|
import os
|
|
@@ -35,9 +36,31 @@ import uuid
|
|
|
35
36
|
from pathlib import Path
|
|
36
37
|
from typing import Iterator, Optional, List
|
|
37
38
|
|
|
38
|
-
from core import
|
|
39
|
+
from core import (
|
|
40
|
+
APError,
|
|
41
|
+
PROJECT_CONFIG_PATH,
|
|
42
|
+
PROJECT_CONFIG_SCHEMA,
|
|
43
|
+
copy_tree,
|
|
44
|
+
ensure_git_repo,
|
|
45
|
+
http_get_status,
|
|
46
|
+
load_effective_config,
|
|
47
|
+
load_managed_config,
|
|
48
|
+
load_project_overrides,
|
|
49
|
+
merge_project_config,
|
|
50
|
+
parse_managed_config_payload,
|
|
51
|
+
parse_project_overrides_payload,
|
|
52
|
+
require_yaml,
|
|
53
|
+
run,
|
|
54
|
+
run_shell,
|
|
55
|
+
)
|
|
39
56
|
from install_integrity import verify_managed_install
|
|
40
|
-
from scaffold_templates import
|
|
57
|
+
from scaffold_templates import (
|
|
58
|
+
MANAGED_FRAMEWORK_DOCS,
|
|
59
|
+
PROJECT_FEEDBACK_PATTERNS,
|
|
60
|
+
PROJECT_OWNED_DOC_ROOTS,
|
|
61
|
+
scaffold_groups,
|
|
62
|
+
templates_for,
|
|
63
|
+
)
|
|
41
64
|
|
|
42
65
|
|
|
43
66
|
_JENKINS_CRUMB_CACHE: dict[tuple[str, str], dict[str, str]] = {}
|
|
@@ -78,6 +101,102 @@ _REVIEW_OUTPUT_MAX_BYTES = 1024 * 1024
|
|
|
78
101
|
_REVIEW_DIFF_ARTIFACT_FORMAT = "git-binary-patch-v1"
|
|
79
102
|
_REVIEW_DIFF_ARTIFACT_MAX_BYTES = 64 * 1024 * 1024
|
|
80
103
|
_REVIEW_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
|
|
104
|
+
_FEEDBACK_SCHEMAS = {
|
|
105
|
+
"auto-coding-skill-feedback/v1",
|
|
106
|
+
"auto-coding-skill-feedback/v2",
|
|
107
|
+
}
|
|
108
|
+
_FEEDBACK_COLLECTION_SCHEMA = "auto-coding-skill-feedback-collection/v2"
|
|
109
|
+
_FEEDBACK_RESOLUTION_SCHEMA = "auto-coding-skill-feedback-resolutions/v1"
|
|
110
|
+
_FEEDBACK_RESOLUTION_POLICY = Path("data/policies/feedback-resolutions-v1.json")
|
|
111
|
+
_FEEDBACK_RESOLUTION_MAX_BYTES = 64 * 1024
|
|
112
|
+
_FEEDBACK_REPORT_MAX_BYTES = 16 * 1024
|
|
113
|
+
_FEEDBACK_PROJECT_MAX_REPORTS = 100
|
|
114
|
+
_FEEDBACK_PROJECT_MAX_ENTRIES = 200
|
|
115
|
+
_FEEDBACK_COLLECTION_MAX_BYTES = 1024 * 1024
|
|
116
|
+
_FEEDBACK_COLLECTION_MAX_REPORTS = 500
|
|
117
|
+
_FEEDBACK_COLLECTION_MAX_PROJECTS = 100
|
|
118
|
+
_PROJECT_CONFIG_RELATIVE = PROJECT_CONFIG_PATH
|
|
119
|
+
_INSTALL_TRANSACTION_RELATIVE = Path(".agents/.auto-coding-skill-install-transaction")
|
|
120
|
+
_EFFECTIVE_CONFIG_PATHS = {
|
|
121
|
+
"docs/ENGINEERING.md",
|
|
122
|
+
_PROJECT_CONFIG_RELATIVE.as_posix(),
|
|
123
|
+
}
|
|
124
|
+
_FEEDBACK_V1_FIELDS = (
|
|
125
|
+
"schema",
|
|
126
|
+
"report_id",
|
|
127
|
+
"status",
|
|
128
|
+
"created_at",
|
|
129
|
+
"project",
|
|
130
|
+
"observed_skill_version",
|
|
131
|
+
"component",
|
|
132
|
+
"kind",
|
|
133
|
+
"impact",
|
|
134
|
+
"origin_surface",
|
|
135
|
+
"suspected_scope",
|
|
136
|
+
"signature",
|
|
137
|
+
"export",
|
|
138
|
+
)
|
|
139
|
+
_FEEDBACK_V2_FIELDS = (
|
|
140
|
+
*_FEEDBACK_V1_FIELDS,
|
|
141
|
+
"updated_at",
|
|
142
|
+
"last_verified_skill_version",
|
|
143
|
+
"resolution",
|
|
144
|
+
)
|
|
145
|
+
_FEEDBACK_STATUSES = {"open", "needs-evidence", "accepted", "duplicate", "resolved", "rejected"}
|
|
146
|
+
_FEEDBACK_ACTIVE_STATUSES = {"open", "needs-evidence", "accepted"}
|
|
147
|
+
_FEEDBACK_KINDS = {"defect", "gap"}
|
|
148
|
+
_FEEDBACK_IMPACTS = {"blocking", "degraded", "minor"}
|
|
149
|
+
_FEEDBACK_ORIGIN_SURFACES = {
|
|
150
|
+
"managed-template",
|
|
151
|
+
"managed-script",
|
|
152
|
+
"managed-agent",
|
|
153
|
+
"cli",
|
|
154
|
+
"installer",
|
|
155
|
+
}
|
|
156
|
+
_FEEDBACK_RESOLUTIONS = {
|
|
157
|
+
"pending",
|
|
158
|
+
"fixed",
|
|
159
|
+
"duplicate",
|
|
160
|
+
"project-config",
|
|
161
|
+
"environment",
|
|
162
|
+
"not-shared",
|
|
163
|
+
"not-reproducible",
|
|
164
|
+
"wont-fix",
|
|
165
|
+
}
|
|
166
|
+
_FEEDBACK_CATALOG_DISPOSITIONS = {
|
|
167
|
+
"fixed",
|
|
168
|
+
"project-config",
|
|
169
|
+
"environment",
|
|
170
|
+
"duplicate",
|
|
171
|
+
"rejected",
|
|
172
|
+
}
|
|
173
|
+
_FEEDBACK_HEADINGS = (
|
|
174
|
+
"Symptom",
|
|
175
|
+
"Expected",
|
|
176
|
+
"Minimal reproduction",
|
|
177
|
+
"Evidence",
|
|
178
|
+
"Workaround",
|
|
179
|
+
"Why shared",
|
|
180
|
+
)
|
|
181
|
+
_FEEDBACK_SAFE_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
|
|
182
|
+
_FEEDBACK_SLUG_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
|
|
183
|
+
_FEEDBACK_SIGNATURE_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
|
|
184
|
+
_FEEDBACK_FILENAME_RE = re.compile(
|
|
185
|
+
r"^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*-[0-9a-f]{8}\.md$"
|
|
186
|
+
)
|
|
187
|
+
_FEEDBACK_SENSITIVE_PATTERNS = (
|
|
188
|
+
re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----", re.IGNORECASE),
|
|
189
|
+
re.compile(r"\bAuthorization\s*:\s*Bearer\s+\S+", re.IGNORECASE),
|
|
190
|
+
re.compile(r"https?://[^\s/:@]+:[^\s/@]+@", re.IGNORECASE),
|
|
191
|
+
re.compile(r"(?:^|[\s`])/(?:Users|home)/[^/\s]+/"),
|
|
192
|
+
re.compile(r"\b[A-Za-z]:\\Users\\[^\\\s]+\\", re.IGNORECASE),
|
|
193
|
+
)
|
|
194
|
+
_FEEDBACK_SEMVER_RE = re.compile(
|
|
195
|
+
r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)"
|
|
196
|
+
r"(?:-(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)"
|
|
197
|
+
r"(?:\.(?:0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?"
|
|
198
|
+
r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$"
|
|
199
|
+
)
|
|
81
200
|
_DEEP_REVIEW_CATEGORIES = {
|
|
82
201
|
"api",
|
|
83
202
|
"auth",
|
|
@@ -168,7 +287,7 @@ _FINAL_GATE_CACHE_ALGORITHM = "final-gate-v1"
|
|
|
168
287
|
_WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
|
|
169
288
|
_FALLBACK_WORKFLOW_MIGRATION_POLICY = {
|
|
170
289
|
"schema_version": 1,
|
|
171
|
-
"managed_versions": {"agents": "4.
|
|
290
|
+
"managed_versions": {"agents": "4.3.1", "engineering": "4.3.1"},
|
|
172
291
|
"known_official_engineering_body_sha256": [
|
|
173
292
|
"d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
|
|
174
293
|
"305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
|
|
@@ -263,7 +382,7 @@ def _join_url(base: str, path: str) -> str:
|
|
|
263
382
|
base = str(base or "").strip().rstrip("/")
|
|
264
383
|
path = str(path or "").strip()
|
|
265
384
|
if not base or not path:
|
|
266
|
-
raise APError("Health URL config incomplete. Fill
|
|
385
|
+
raise APError("Health URL config incomplete. Fill the project configuration overlay.")
|
|
267
386
|
if not path.startswith("/"):
|
|
268
387
|
path = "/" + path
|
|
269
388
|
return base + path
|
|
@@ -391,7 +510,7 @@ def _require_http_url(field: str, value: object) -> str:
|
|
|
391
510
|
raw = _text(value).rstrip("/")
|
|
392
511
|
parsed = urllib.parse.urlparse(raw)
|
|
393
512
|
if not _is_explicit_fill(raw) or parsed.scheme not in {"http", "https"} or not parsed.netloc:
|
|
394
|
-
raise APError(f"Missing or invalid {field}; fill an http/https URL in
|
|
513
|
+
raise APError(f"Missing or invalid {field}; fill an http/https URL in the project configuration overlay.")
|
|
395
514
|
return raw
|
|
396
515
|
|
|
397
516
|
|
|
@@ -619,7 +738,7 @@ def _jenkins_api_get_json(
|
|
|
619
738
|
f"Jenkins API request failed: {url}\n"
|
|
620
739
|
f"HTTP 403\n{body or '(empty response body)'}\n"
|
|
621
740
|
"Jenkins may require crumb/CSRF handling, but no crumb issuer endpoint was available. "
|
|
622
|
-
"Fill jenkins.base_url in
|
|
741
|
+
"Fill jenkins.base_url in the project configuration overlay if needed."
|
|
623
742
|
) from exc
|
|
624
743
|
else:
|
|
625
744
|
raise APError(
|
|
@@ -727,7 +846,7 @@ def _resolve_jenkins_job_url(
|
|
|
727
846
|
return _jenkins_job_url_from_name(base_url, requested_name)
|
|
728
847
|
raise APError(
|
|
729
848
|
f"Cannot resolve Jenkins job URL for job '{requested_name}'. "
|
|
730
|
-
"Pass --job-url, or fill the selected Jenkins endpoint in
|
|
849
|
+
"Pass --job-url, or fill the selected Jenkins endpoint in the project configuration overlay."
|
|
731
850
|
)
|
|
732
851
|
if configured_url:
|
|
733
852
|
return configured_url.rstrip("/")
|
|
@@ -842,559 +961,1970 @@ def _inferred_gate_commands(repo: Path) -> dict[str, str]:
|
|
|
842
961
|
return {}
|
|
843
962
|
|
|
844
963
|
|
|
845
|
-
def _initialize_engineering_defaults(path: Path, repo: Path) -> None:
|
|
846
|
-
if not path.exists():
|
|
847
|
-
return
|
|
848
|
-
text = path.read_text(encoding="utf-8")
|
|
849
|
-
updated = text.replace(
|
|
850
|
-
'project:\n name: ""',
|
|
851
|
-
f"project:\n name: {json.dumps(repo.name, ensure_ascii=False)}",
|
|
852
|
-
1,
|
|
853
|
-
)
|
|
854
|
-
for key, gate_command in _inferred_gate_commands(repo).items():
|
|
855
|
-
for default_value in ['""', '"git diff --check"']:
|
|
856
|
-
candidate = updated.replace(
|
|
857
|
-
f" {key}: {default_value}",
|
|
858
|
-
f" {key}: {json.dumps(gate_command)}",
|
|
859
|
-
1,
|
|
860
|
-
)
|
|
861
|
-
if candidate != updated:
|
|
862
|
-
updated = candidate
|
|
863
|
-
break
|
|
864
|
-
if updated != text:
|
|
865
|
-
path.write_text(updated, encoding="utf-8")
|
|
866
|
-
|
|
867
|
-
|
|
868
964
|
def _mapping(value: object) -> dict:
|
|
869
965
|
return value if isinstance(value, dict) else {}
|
|
870
966
|
|
|
871
967
|
|
|
872
|
-
|
|
873
|
-
if not isinstance(value, list):
|
|
874
|
-
return []
|
|
875
|
-
return [item.strip() for item in value if isinstance(item, str) and item.strip()]
|
|
876
|
-
|
|
968
|
+
_NO_CONFIG_DIFF = object()
|
|
877
969
|
|
|
878
|
-
def _copy_scalar_path(source: dict, target: dict, path: tuple[str, ...]) -> None:
|
|
879
|
-
current: object = source
|
|
880
|
-
for key in path:
|
|
881
|
-
if not isinstance(current, dict) or key not in current:
|
|
882
|
-
return
|
|
883
|
-
current = current[key]
|
|
884
|
-
destination = target
|
|
885
|
-
for key in path[:-1]:
|
|
886
|
-
destination = destination[key]
|
|
887
|
-
expected = destination[path[-1]]
|
|
888
|
-
compatible = (
|
|
889
|
-
(isinstance(expected, bool) and isinstance(current, bool))
|
|
890
|
-
or (isinstance(expected, str) and isinstance(current, str))
|
|
891
|
-
or (
|
|
892
|
-
isinstance(expected, (int, float))
|
|
893
|
-
and not isinstance(expected, bool)
|
|
894
|
-
and isinstance(current, (int, float))
|
|
895
|
-
and not isinstance(current, bool)
|
|
896
|
-
)
|
|
897
|
-
)
|
|
898
|
-
if compatible:
|
|
899
|
-
destination[path[-1]] = current
|
|
900
|
-
|
|
901
|
-
|
|
902
|
-
def _normalize_validation_routes(value: object) -> list[dict]:
|
|
903
|
-
routes: list[dict] = []
|
|
904
|
-
if not isinstance(value, list):
|
|
905
|
-
return routes
|
|
906
|
-
for raw in value:
|
|
907
|
-
if not isinstance(raw, dict):
|
|
908
|
-
continue
|
|
909
|
-
route: dict = {}
|
|
910
|
-
name = _text(raw.get("name"))
|
|
911
|
-
paths = _string_list(raw.get("paths"))
|
|
912
|
-
commands = [_command_name(item) for item in _string_list(raw.get("commands"))]
|
|
913
|
-
commands = [item for item in commands if item]
|
|
914
|
-
if name:
|
|
915
|
-
route["name"] = name
|
|
916
|
-
if paths:
|
|
917
|
-
route["paths"] = paths
|
|
918
|
-
exclude = _string_list(raw.get("exclude"))
|
|
919
|
-
if exclude:
|
|
920
|
-
route["exclude"] = exclude
|
|
921
|
-
if commands:
|
|
922
|
-
route["commands"] = commands
|
|
923
|
-
timeout = raw.get("timeout_seconds")
|
|
924
|
-
if isinstance(timeout, (int, float)) and not isinstance(timeout, bool) and timeout > 0:
|
|
925
|
-
route["timeout_seconds"] = timeout
|
|
926
|
-
if paths and commands:
|
|
927
|
-
routes.append(route)
|
|
928
|
-
return routes
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
def _normalize_risk_rules(value: object) -> list[dict]:
|
|
932
|
-
rules: list[dict] = []
|
|
933
|
-
if not isinstance(value, list):
|
|
934
|
-
return rules
|
|
935
|
-
for raw in value:
|
|
936
|
-
if not isinstance(raw, dict):
|
|
937
|
-
continue
|
|
938
|
-
rule: dict = {}
|
|
939
|
-
name = _text(raw.get("name"))
|
|
940
|
-
paths = _string_list(raw.get("paths"))
|
|
941
|
-
if name:
|
|
942
|
-
rule["name"] = name
|
|
943
|
-
if paths:
|
|
944
|
-
rule["paths"] = paths
|
|
945
|
-
profile = _text(raw.get("profile")).lower()
|
|
946
|
-
if profile in _WORKFLOW_PROFILES - {"auto"}:
|
|
947
|
-
rule["profile"] = profile
|
|
948
|
-
for key in ["review", "design"]:
|
|
949
|
-
value_text = _text(raw.get(key)).lower()
|
|
950
|
-
if value_text in {"required", "true", "yes", "false", "no"}:
|
|
951
|
-
rule[key] = value_text
|
|
952
|
-
if paths:
|
|
953
|
-
rules.append(rule)
|
|
954
|
-
return rules
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
def _normalize_layer_rules(value: object) -> list[dict]:
|
|
958
|
-
rules: list[dict] = []
|
|
959
|
-
if not isinstance(value, list):
|
|
960
|
-
return rules
|
|
961
|
-
for raw in value:
|
|
962
|
-
if not isinstance(raw, dict):
|
|
963
|
-
continue
|
|
964
|
-
paths = _string_list(raw.get("paths"))
|
|
965
|
-
forbidden = _string_list(raw.get("forbidden_imports"))
|
|
966
|
-
if not paths or not forbidden:
|
|
967
|
-
continue
|
|
968
|
-
rule = {"paths": paths, "forbidden_imports": forbidden}
|
|
969
|
-
name = _text(raw.get("name"))
|
|
970
|
-
if name:
|
|
971
|
-
rule = {"name": name, **rule}
|
|
972
|
-
rules.append(rule)
|
|
973
|
-
return rules
|
|
974
970
|
|
|
971
|
+
def _config_values_equal(left: object, right: object) -> bool:
|
|
972
|
+
"""Compare parsed configuration without Python's bool/number coercions."""
|
|
973
|
+
if type(left) is not type(right):
|
|
974
|
+
return False
|
|
975
|
+
if isinstance(left, dict):
|
|
976
|
+
return left.keys() == right.keys() and all(
|
|
977
|
+
_config_values_equal(left[key], right[key]) for key in left
|
|
978
|
+
)
|
|
979
|
+
if isinstance(left, list):
|
|
980
|
+
return len(left) == len(right) and all(
|
|
981
|
+
_config_values_equal(left_item, right_item)
|
|
982
|
+
for left_item, right_item in zip(left, right)
|
|
983
|
+
)
|
|
984
|
+
return left == right
|
|
975
985
|
|
|
976
|
-
def _converged_engineering_document(repo: Path, template_path: Path) -> str:
|
|
977
|
-
template_cfg, template_body = _read_frontmatter_markdown(template_path)
|
|
978
|
-
engineering = repo / "docs" / "ENGINEERING.md"
|
|
979
|
-
current_cfg: dict = {}
|
|
980
|
-
if engineering.exists():
|
|
981
|
-
try:
|
|
982
|
-
current_cfg, _ = _read_frontmatter_markdown(engineering)
|
|
983
|
-
except Exception:
|
|
984
|
-
# Initialization is an authoritative reset. Malformed legacy policy
|
|
985
|
-
# must not prevent the current schema from taking effect.
|
|
986
|
-
current_cfg = {}
|
|
987
|
-
|
|
988
|
-
converged = json.loads(json.dumps(template_cfg))
|
|
989
|
-
preserve_scalar_paths = [
|
|
990
|
-
("project", "name"),
|
|
991
|
-
("project", "repo_root"),
|
|
992
|
-
("project", "stack"),
|
|
993
|
-
("access", "project", "frontend", "url"),
|
|
994
|
-
("access", "project", "frontend", "username"),
|
|
995
|
-
("access", "project", "frontend", "password"),
|
|
996
|
-
("access", "project", "backend", "url"),
|
|
997
|
-
("access", "project", "backend", "username"),
|
|
998
|
-
("access", "project", "backend", "password"),
|
|
999
|
-
("access", "jenkins", "frontend", "url"),
|
|
1000
|
-
("access", "jenkins", "frontend", "username"),
|
|
1001
|
-
("access", "jenkins", "frontend", "password"),
|
|
1002
|
-
("access", "jenkins", "backend", "url"),
|
|
1003
|
-
("access", "jenkins", "backend", "username"),
|
|
1004
|
-
("access", "jenkins", "backend", "password"),
|
|
1005
|
-
("access", "gitlab", "url"),
|
|
1006
|
-
("access", "gitlab", "username"),
|
|
1007
|
-
("access", "gitlab", "password"),
|
|
1008
|
-
("access", "nexus", "frontend", "url"),
|
|
1009
|
-
("access", "nexus", "frontend", "username"),
|
|
1010
|
-
("access", "nexus", "frontend", "password"),
|
|
1011
|
-
("concurrency", "base_ref"),
|
|
1012
|
-
("concurrency", "target_branch"),
|
|
1013
|
-
("concurrency", "branch_prefix"),
|
|
1014
|
-
("concurrency", "worktree_root"),
|
|
1015
|
-
("concurrency", "cleanup_merged"),
|
|
1016
|
-
("concurrency", "delete_remote_branch"),
|
|
1017
|
-
("validation", "max_command_seconds"),
|
|
1018
|
-
("validation", "max_total_seconds"),
|
|
1019
|
-
("structure", "enabled"),
|
|
1020
|
-
("structure", "enforcement"),
|
|
1021
|
-
("structure", "architecture_standard"),
|
|
1022
|
-
("structure", "layer_rules", "enabled"),
|
|
1023
|
-
("structure", "layer_rules", "block"),
|
|
1024
|
-
("optimization", "completion_policy"),
|
|
1025
|
-
("optimization", "require_baseline_for_global_review"),
|
|
1026
|
-
("optimization", "report_accepted_debt_as_findings"),
|
|
1027
|
-
("docs", "api_docs_required"),
|
|
1028
|
-
]
|
|
1029
|
-
for field_path in preserve_scalar_paths:
|
|
1030
|
-
_copy_scalar_path(current_cfg, converged, field_path)
|
|
1031
|
-
|
|
1032
|
-
current_concurrency = _mapping(current_cfg.get("concurrency"))
|
|
1033
|
-
isolation = _text(current_concurrency.get("isolation")).lower()
|
|
1034
|
-
if isolation in {"adaptive", "worktree"}:
|
|
1035
|
-
converged["concurrency"]["isolation"] = isolation
|
|
1036
|
-
converged["concurrency"]["disposable_ignored"] = _string_list(
|
|
1037
|
-
current_concurrency.get("disposable_ignored")
|
|
1038
|
-
)
|
|
1039
|
-
|
|
1040
|
-
current_commands = _mapping(current_cfg.get("commands"))
|
|
1041
|
-
current_validation = _mapping(current_cfg.get("validation"))
|
|
1042
|
-
routes = _normalize_validation_routes(current_validation.get("routes"))
|
|
1043
|
-
referenced_commands = {
|
|
1044
|
-
command
|
|
1045
|
-
for route in routes
|
|
1046
|
-
for command in _string_list(route.get("commands"))
|
|
1047
|
-
}
|
|
1048
|
-
referenced_commands.add("project_fast")
|
|
1049
|
-
commands = {
|
|
1050
|
-
str(name): value.strip()
|
|
1051
|
-
for name, value in current_commands.items()
|
|
1052
|
-
if name in referenced_commands and isinstance(name, str) and isinstance(value, str) and value.strip()
|
|
1053
|
-
}
|
|
1054
|
-
inferred = _inferred_gate_commands(repo)
|
|
1055
|
-
if not commands.get("project_fast") and inferred.get("project_fast"):
|
|
1056
|
-
commands["project_fast"] = inferred["project_fast"]
|
|
1057
|
-
converged["commands"].update(commands)
|
|
1058
|
-
|
|
1059
|
-
converged["validation"]["routes"] = routes
|
|
1060
|
-
converged["risk"]["rules"] = _normalize_risk_rules(
|
|
1061
|
-
_mapping(current_cfg.get("risk")).get("rules")
|
|
1062
|
-
)
|
|
1063
|
-
current_structure = _mapping(current_cfg.get("structure"))
|
|
1064
|
-
for key in ("exclude", "allow_large_files", "reusable_tool_dirs"):
|
|
1065
|
-
if isinstance(current_structure.get(key), list):
|
|
1066
|
-
converged["structure"][key] = _string_list(current_structure.get(key))
|
|
1067
|
-
for key in (
|
|
1068
|
-
"max_file_lines_warn",
|
|
1069
|
-
"max_file_lines_block",
|
|
1070
|
-
"max_function_lines_warn",
|
|
1071
|
-
"max_added_lines_to_large_file",
|
|
1072
|
-
):
|
|
1073
|
-
value = current_structure.get(key)
|
|
1074
|
-
if isinstance(value, int) and not isinstance(value, bool):
|
|
1075
|
-
converged["structure"][key] = value
|
|
1076
|
-
for key in (
|
|
1077
|
-
"require_reuse_search",
|
|
1078
|
-
"block_new_responsibility_in_large_file",
|
|
1079
|
-
"block_warnings",
|
|
1080
|
-
):
|
|
1081
|
-
value = current_structure.get(key)
|
|
1082
|
-
if isinstance(value, bool):
|
|
1083
|
-
converged["structure"][key] = value
|
|
1084
|
-
converged["structure"]["accepted_debt_paths"] = _string_list(
|
|
1085
|
-
current_structure.get("accepted_debt_paths")
|
|
1086
|
-
)
|
|
1087
|
-
current_layers = _mapping(current_structure.get("layer_rules"))
|
|
1088
|
-
converged["structure"]["layer_rules"]["rules"] = _normalize_layer_rules(
|
|
1089
|
-
current_layers.get("rules")
|
|
1090
|
-
)
|
|
1091
|
-
|
|
1092
|
-
if not _text(_mapping(converged.get("project")).get("name")):
|
|
1093
|
-
converged["project"]["name"] = repo.name
|
|
1094
|
-
dumped = require_yaml().safe_dump(converged, allow_unicode=True, sort_keys=False).strip()
|
|
1095
|
-
return f"---\n{dumped}\n---\n{template_body.lstrip()}"
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
_PROJECT_ARTIFACT_PATTERNS = (
|
|
1099
|
-
"docs/architecture/*.md",
|
|
1100
|
-
"docs/architecture/adr/*.md",
|
|
1101
|
-
"docs/deployment/deploy-records/*.md",
|
|
1102
|
-
"docs/design/*.md",
|
|
1103
|
-
"docs/interfaces/*.md",
|
|
1104
|
-
"docs/reviews/*.md",
|
|
1105
|
-
)
|
|
1106
986
|
|
|
987
|
+
def _config_semantic_diff(current: object, base: object, path: tuple[str, ...] = ()) -> object:
|
|
988
|
+
"""Return only project-owned values, excluding the managed release identity."""
|
|
989
|
+
if path == ("workflow", "skill_version"):
|
|
990
|
+
return _NO_CONFIG_DIFF
|
|
991
|
+
if isinstance(current, dict) and isinstance(base, dict):
|
|
992
|
+
result: dict = {}
|
|
993
|
+
for key, value in current.items():
|
|
994
|
+
field_path = (*path, str(key))
|
|
995
|
+
if key not in base:
|
|
996
|
+
if field_path != ("workflow", "skill_version"):
|
|
997
|
+
result[key] = json.loads(json.dumps(value))
|
|
998
|
+
continue
|
|
999
|
+
difference = _config_semantic_diff(value, base[key], field_path)
|
|
1000
|
+
if difference is not _NO_CONFIG_DIFF:
|
|
1001
|
+
result[key] = difference
|
|
1002
|
+
return result if result else _NO_CONFIG_DIFF
|
|
1003
|
+
if not _config_values_equal(current, base):
|
|
1004
|
+
return json.loads(json.dumps(current))
|
|
1005
|
+
return _NO_CONFIG_DIFF
|
|
1006
|
+
|
|
1007
|
+
|
|
1008
|
+
def _config_difference_conflicts(
|
|
1009
|
+
difference: object,
|
|
1010
|
+
current: object,
|
|
1011
|
+
effective: object,
|
|
1012
|
+
path: tuple[str, ...] = (),
|
|
1013
|
+
) -> list[str]:
|
|
1014
|
+
"""Find legacy project values not preserved exactly by an existing overlay."""
|
|
1015
|
+
if difference is _NO_CONFIG_DIFF:
|
|
1016
|
+
return []
|
|
1017
|
+
if isinstance(difference, dict):
|
|
1018
|
+
if not isinstance(current, dict) or not isinstance(effective, dict):
|
|
1019
|
+
return [".".join(path) or "(root)"]
|
|
1020
|
+
conflicts: list[str] = []
|
|
1021
|
+
for key, value in difference.items():
|
|
1022
|
+
field_path = (*path, str(key))
|
|
1023
|
+
if key not in current or key not in effective:
|
|
1024
|
+
conflicts.append(".".join(field_path))
|
|
1025
|
+
continue
|
|
1026
|
+
conflicts.extend(
|
|
1027
|
+
_config_difference_conflicts(
|
|
1028
|
+
value,
|
|
1029
|
+
current[key],
|
|
1030
|
+
effective[key],
|
|
1031
|
+
field_path,
|
|
1032
|
+
)
|
|
1033
|
+
)
|
|
1034
|
+
return conflicts
|
|
1035
|
+
return [] if _config_values_equal(current, effective) else [".".join(path) or "(root)"]
|
|
1107
1036
|
|
|
1108
|
-
def _is_allowed_project_doc(rel: Path) -> bool:
|
|
1109
|
-
return any(rel.match(pattern) for pattern in _PROJECT_ARTIFACT_PATTERNS)
|
|
1110
1037
|
|
|
1038
|
+
_INSTALLED_ENGINEERING_TEMPLATE = Path(
|
|
1039
|
+
".agents/skills/auto-coding-skill/data/templates/ENGINEERING.md"
|
|
1040
|
+
)
|
|
1041
|
+
_INSTALLED_MANIFEST = Path(".agents/managed-install.json")
|
|
1111
1042
|
|
|
1112
|
-
def cmd_project_converge(args: argparse.Namespace) -> None:
|
|
1113
|
-
repo = Path(args.repo).resolve()
|
|
1114
|
-
template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
|
|
1115
|
-
engineering = repo / "docs" / "ENGINEERING.md"
|
|
1116
|
-
output = _converged_engineering_document(repo, template)
|
|
1117
|
-
current = engineering.read_text(encoding="utf-8") if engineering.exists() else ""
|
|
1118
|
-
changed = not bool(current)
|
|
1119
|
-
if current:
|
|
1120
|
-
try:
|
|
1121
|
-
current_cfg, current_body = _parse_frontmatter_markdown_text(current, engineering)
|
|
1122
|
-
output_cfg, output_body = _parse_frontmatter_markdown_text(output, engineering)
|
|
1123
|
-
changed = current_cfg != output_cfg or current_body != output_body
|
|
1124
|
-
except Exception:
|
|
1125
|
-
changed = True
|
|
1126
|
-
actions: list[dict] = []
|
|
1127
|
-
version = _text(_mapping(_read_frontmatter_markdown(template)[0].get("workflow")).get("skill_version")) or "current"
|
|
1128
1043
|
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
archive.write_text(content, encoding="utf-8")
|
|
1044
|
+
def _installed_template_config(repo: Path) -> dict | None:
|
|
1045
|
+
relative = _INSTALLED_ENGINEERING_TEMPLATE
|
|
1046
|
+
payload = _safe_read_project_file(repo, relative, max_bytes=1024 * 1024)
|
|
1047
|
+
if payload is None:
|
|
1048
|
+
return None
|
|
1049
|
+
manifest_payload = _safe_read_project_file(repo, _INSTALLED_MANIFEST, max_bytes=4 * 1024 * 1024)
|
|
1050
|
+
if manifest_payload is None:
|
|
1051
|
+
raise APError(
|
|
1052
|
+
"Cannot trust the installed default template without .agents/managed-install.json; "
|
|
1053
|
+
"no files were written."
|
|
1054
|
+
)
|
|
1141
1055
|
|
|
1142
|
-
def
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
if not archive.exists():
|
|
1150
|
-
actions.append({"action": "archive", "path": _repo_rel(repo, archive), "detail": label})
|
|
1151
|
-
if args.write:
|
|
1152
|
-
archive.parent.mkdir(parents=True, exist_ok=True)
|
|
1153
|
-
archive.write_bytes(content)
|
|
1056
|
+
def reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict:
|
|
1057
|
+
result: dict = {}
|
|
1058
|
+
for key, value in pairs:
|
|
1059
|
+
if not isinstance(key, str) or key in result:
|
|
1060
|
+
raise ValueError("invalid manifest mapping")
|
|
1061
|
+
result[key] = value
|
|
1062
|
+
return result
|
|
1154
1063
|
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
|
-
|
|
1064
|
+
try:
|
|
1065
|
+
manifest = json.loads(
|
|
1066
|
+
manifest_payload.decode("utf-8"),
|
|
1067
|
+
object_pairs_hook=reject_duplicate_keys,
|
|
1159
1068
|
)
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1069
|
+
except (UnicodeDecodeError, json.JSONDecodeError, ValueError) as exc:
|
|
1070
|
+
raise APError("Installed managed manifest is invalid; no files were written.") from exc
|
|
1071
|
+
if (
|
|
1072
|
+
not isinstance(manifest, dict)
|
|
1073
|
+
or manifest.get("schema_version") != 1
|
|
1074
|
+
or manifest.get("manifest_path") != _INSTALLED_MANIFEST.as_posix()
|
|
1075
|
+
or not isinstance(manifest.get("entries"), list)
|
|
1076
|
+
):
|
|
1077
|
+
raise APError("Installed managed manifest is invalid; no files were written.")
|
|
1078
|
+
if len(manifest["entries"]) > 10000:
|
|
1079
|
+
raise APError("Installed managed manifest has too many entries; no files were written.")
|
|
1080
|
+
matches = [
|
|
1081
|
+
entry
|
|
1082
|
+
for entry in manifest["entries"]
|
|
1083
|
+
if isinstance(entry, dict) and entry.get("path") == relative.as_posix()
|
|
1084
|
+
]
|
|
1085
|
+
manifest_version = _text(manifest.get("skill_version"))
|
|
1086
|
+
if not re.fullmatch(r"(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)", manifest_version):
|
|
1087
|
+
raise APError("Installed managed manifest has an invalid Skill version; no files were written.")
|
|
1088
|
+
if len(matches) != 1:
|
|
1089
|
+
raise APError("Installed default template is not bound by the managed manifest; no files were written.")
|
|
1090
|
+
entry = matches[0]
|
|
1091
|
+
expected_hash = _text(entry.get("sha256"))
|
|
1092
|
+
if (
|
|
1093
|
+
entry.get("ownership") != "exact"
|
|
1094
|
+
or entry.get("source") != "skill/data/templates/ENGINEERING.md"
|
|
1095
|
+
or entry.get("version") != manifest_version
|
|
1096
|
+
or not re.fullmatch(r"[0-9a-f]{64}", expected_hash)
|
|
1097
|
+
or hashlib.sha256(payload).hexdigest() != expected_hash
|
|
1098
|
+
):
|
|
1099
|
+
raise APError("Installed default template failed its managed manifest identity check; no files were written.")
|
|
1100
|
+
config = parse_managed_config_payload(payload)
|
|
1101
|
+
config_version = _text(_mapping(config.get("workflow")).get("skill_version"))
|
|
1102
|
+
if config_version != manifest_version:
|
|
1103
|
+
raise APError("Installed default template version is not bound to its manifest; no files were written.")
|
|
1104
|
+
return config
|
|
1105
|
+
|
|
1106
|
+
|
|
1107
|
+
def _render_project_overlay(overrides: dict) -> bytes:
|
|
1108
|
+
document = {"schema": PROJECT_CONFIG_SCHEMA, "overrides": overrides}
|
|
1109
|
+
dumped = require_yaml().safe_dump(document, allow_unicode=True, sort_keys=False)
|
|
1110
|
+
payload = dumped.encode("utf-8")
|
|
1111
|
+
# The installer must never create an overlay that its own runtime rejects.
|
|
1112
|
+
parse_project_overrides_payload(payload)
|
|
1113
|
+
return payload
|
|
1169
1114
|
|
|
1170
|
-
for rel, canonical in sorted(templates_for("all").items()):
|
|
1171
|
-
target = repo / rel
|
|
1172
|
-
existing = target.read_text(encoding="utf-8") if target.exists() else ""
|
|
1173
|
-
managed = rel in MANAGED_FRAMEWORK_DOCS
|
|
1174
|
-
if existing and (not managed or existing == canonical):
|
|
1175
|
-
continue
|
|
1176
|
-
if existing:
|
|
1177
|
-
archive_previous(target, existing, "previous managed documentation template")
|
|
1178
|
-
actions.append({"action": "create" if not existing else "replace", "path": rel})
|
|
1179
|
-
if args.write:
|
|
1180
|
-
target.parent.mkdir(parents=True, exist_ok=True)
|
|
1181
|
-
target.write_text(canonical, encoding="utf-8")
|
|
1182
1115
|
|
|
1183
|
-
|
|
1116
|
+
def _project_config_convergence_plan(repo: Path, template: Path) -> dict:
|
|
1117
|
+
template_payload = template.read_bytes()
|
|
1118
|
+
template_cfg = parse_managed_config_payload(template_payload)
|
|
1119
|
+
try:
|
|
1120
|
+
template_text = template_payload.decode("utf-8")
|
|
1121
|
+
except UnicodeDecodeError as exc:
|
|
1122
|
+
raise APError("Managed Skill template must be UTF-8.") from exc
|
|
1123
|
+
current_payload = _safe_read_project_file(
|
|
1124
|
+
repo,
|
|
1184
1125
|
Path("docs/ENGINEERING.md"),
|
|
1185
|
-
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
|
-
|
|
1189
|
-
if
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
1193
|
-
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
|
-
|
|
1203
|
-
|
|
1204
|
-
|
|
1126
|
+
max_bytes=1024 * 1024,
|
|
1127
|
+
)
|
|
1128
|
+
current_cfg: dict | None = None
|
|
1129
|
+
current_text = ""
|
|
1130
|
+
if current_payload is not None:
|
|
1131
|
+
try:
|
|
1132
|
+
current_text = current_payload.decode("utf-8")
|
|
1133
|
+
except UnicodeDecodeError as exc:
|
|
1134
|
+
raise APError("Managed project configuration must be UTF-8.") from exc
|
|
1135
|
+
current_cfg = parse_managed_config_payload(current_payload)
|
|
1136
|
+
|
|
1137
|
+
# Always validate an existing overlay before any installer write. Its bytes
|
|
1138
|
+
# are project-owned and are never normalized by ordinary convergence.
|
|
1139
|
+
overlay_payload = _safe_read_project_file(
|
|
1140
|
+
repo,
|
|
1141
|
+
_PROJECT_CONFIG_RELATIVE,
|
|
1142
|
+
max_bytes=128 * 1024,
|
|
1143
|
+
)
|
|
1144
|
+
overrides = (
|
|
1145
|
+
parse_project_overrides_payload(overlay_payload)
|
|
1146
|
+
if overlay_payload is not None
|
|
1147
|
+
else {}
|
|
1148
|
+
)
|
|
1149
|
+
old_base = None
|
|
1150
|
+
if current_cfg is not None:
|
|
1151
|
+
# A completed target document is self-identical to the trusted source
|
|
1152
|
+
# template, so retry does not depend on the previous install manifest.
|
|
1153
|
+
# Legacy/custom documents still require a manifest-bound old base.
|
|
1154
|
+
old_base = (
|
|
1155
|
+
template_cfg
|
|
1156
|
+
if current_payload == template_payload
|
|
1157
|
+
else _installed_template_config(repo)
|
|
1158
|
+
)
|
|
1159
|
+
overlay_output: bytes | None = None
|
|
1160
|
+
migrated_paths: list[str] = []
|
|
1161
|
+
|
|
1162
|
+
if overlay_payload is None:
|
|
1163
|
+
if current_cfg is not None and old_base is None:
|
|
1164
|
+
current_version = _text(_mapping(current_cfg.get("workflow")).get("skill_version"))
|
|
1165
|
+
template_version = _text(_mapping(template_cfg.get("workflow")).get("skill_version"))
|
|
1166
|
+
if current_version != template_version:
|
|
1167
|
+
raise APError(
|
|
1168
|
+
"Cannot migrate project configuration without its installed default template; "
|
|
1169
|
+
"no files were written. Restore the current .agents Skill copy or create the "
|
|
1170
|
+
"project overlay explicitly."
|
|
1171
|
+
)
|
|
1172
|
+
old_base = template_cfg
|
|
1173
|
+
difference = (
|
|
1174
|
+
_config_semantic_diff(current_cfg, old_base or template_cfg)
|
|
1175
|
+
if current_cfg is not None
|
|
1176
|
+
else _NO_CONFIG_DIFF
|
|
1177
|
+
)
|
|
1178
|
+
overrides = difference if isinstance(difference, dict) else {}
|
|
1179
|
+
if current_cfg is not None:
|
|
1180
|
+
semantic_base = old_base or template_cfg
|
|
1181
|
+
current_version = _text(_mapping(current_cfg.get("workflow")).get("skill_version"))
|
|
1182
|
+
base_version = _text(_mapping(semantic_base.get("workflow")).get("skill_version"))
|
|
1183
|
+
if current_version != base_version:
|
|
1184
|
+
raise APError(
|
|
1185
|
+
"Installed default template version does not match docs/ENGINEERING.md; "
|
|
1186
|
+
"no files were written."
|
|
1187
|
+
)
|
|
1188
|
+
if not _config_values_equal(
|
|
1189
|
+
merge_project_config(semantic_base, overrides),
|
|
1190
|
+
current_cfg,
|
|
1205
1191
|
):
|
|
1206
|
-
|
|
1207
|
-
|
|
1208
|
-
|
|
1209
|
-
|
|
1192
|
+
raise APError(
|
|
1193
|
+
"Project configuration migration could not prove semantic equivalence; "
|
|
1194
|
+
"no files were written."
|
|
1195
|
+
)
|
|
1196
|
+
project_cfg = overrides.setdefault("project", {})
|
|
1197
|
+
if not isinstance(project_cfg, dict):
|
|
1198
|
+
raise APError("Legacy project.project must be a mapping before configuration migration.")
|
|
1199
|
+
if not _text(project_cfg.get("name")):
|
|
1200
|
+
project_cfg["name"] = repo.name
|
|
1201
|
+
if current_cfg is None:
|
|
1202
|
+
inferred = _inferred_gate_commands(repo)
|
|
1203
|
+
if inferred:
|
|
1204
|
+
overrides.setdefault("commands", {}).update(inferred)
|
|
1205
|
+
# Validate protected fields and merge behavior before writing the new file.
|
|
1206
|
+
merge_project_config(template_cfg, overrides)
|
|
1207
|
+
overlay_output = _render_project_overlay(overrides)
|
|
1208
|
+
migrated_paths = sorted(_flatten_config_paths(overrides))
|
|
1209
|
+
elif current_cfg is not None:
|
|
1210
|
+
if old_base is None:
|
|
1211
|
+
raise APError(
|
|
1212
|
+
"Cannot verify an existing project overlay without the installed default template; "
|
|
1213
|
+
"no files were written."
|
|
1214
|
+
)
|
|
1215
|
+
current_version = _text(_mapping(current_cfg.get("workflow")).get("skill_version"))
|
|
1216
|
+
base_version = _text(_mapping(old_base.get("workflow")).get("skill_version"))
|
|
1217
|
+
if current_version != base_version:
|
|
1218
|
+
raise APError(
|
|
1219
|
+
"Installed default template version does not match docs/ENGINEERING.md; "
|
|
1220
|
+
"no files were written."
|
|
1221
|
+
)
|
|
1222
|
+
legacy_difference = _config_semantic_diff(current_cfg, old_base)
|
|
1223
|
+
legacy_overrides = legacy_difference if isinstance(legacy_difference, dict) else {}
|
|
1224
|
+
if not _config_values_equal(
|
|
1225
|
+
merge_project_config(old_base, legacy_overrides),
|
|
1226
|
+
current_cfg,
|
|
1227
|
+
):
|
|
1228
|
+
raise APError(
|
|
1229
|
+
"Legacy project configuration cannot be represented as additive overrides; "
|
|
1230
|
+
"no files were written. Restore the deleted default field or create an explicit "
|
|
1231
|
+
"project overlay after reconciling the intended value."
|
|
1232
|
+
)
|
|
1233
|
+
legacy_effective = merge_project_config(old_base, overrides)
|
|
1234
|
+
conflicts = _config_difference_conflicts(
|
|
1235
|
+
legacy_difference,
|
|
1236
|
+
current_cfg,
|
|
1237
|
+
legacy_effective,
|
|
1238
|
+
)
|
|
1239
|
+
if conflicts:
|
|
1240
|
+
raise APError(
|
|
1241
|
+
"Existing project overlay conflicts with legacy project configuration; "
|
|
1242
|
+
"no files were written. Preserve these paths exactly in "
|
|
1243
|
+
"docs/project/auto-coding-skill.yaml: "
|
|
1244
|
+
+ ", ".join(sorted(conflicts))
|
|
1245
|
+
)
|
|
1246
|
+
merge_project_config(template_cfg, overrides)
|
|
1210
1247
|
|
|
1211
|
-
|
|
1212
|
-
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
|
|
1218
|
-
print("[project-converge] OK: already current")
|
|
1248
|
+
return {
|
|
1249
|
+
"engineering_output": template_text,
|
|
1250
|
+
"engineering_current": current_text,
|
|
1251
|
+
"overlay_current": overlay_payload,
|
|
1252
|
+
"overlay_output": overlay_output,
|
|
1253
|
+
"migrated_paths": migrated_paths,
|
|
1254
|
+
}
|
|
1219
1255
|
|
|
1220
1256
|
|
|
1221
|
-
def
|
|
1222
|
-
|
|
1223
|
-
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
|
-
if _text(workflow_cfg.get("mode")).lower() != "dev":
|
|
1229
|
-
workflow_cfg["mode"] = "dev"
|
|
1230
|
-
changed.append("workflow.mode")
|
|
1231
|
-
if _text(workflow_cfg.get("completion")).lower() != "push":
|
|
1232
|
-
workflow_cfg["completion"] = "push"
|
|
1233
|
-
changed.append("workflow.completion")
|
|
1234
|
-
if _text(workflow_cfg.get("skill_version")) != "4.2.8":
|
|
1235
|
-
workflow_cfg["skill_version"] = "4.2.8"
|
|
1236
|
-
changed.append("workflow.skill_version")
|
|
1237
|
-
|
|
1238
|
-
commands_cfg = cfg.setdefault("commands", {})
|
|
1239
|
-
if not isinstance(commands_cfg, dict):
|
|
1240
|
-
commands_cfg = {}
|
|
1241
|
-
cfg["commands"] = commands_cfg
|
|
1242
|
-
current_changed_gate = _text(commands_cfg.get("gate_changed"))
|
|
1243
|
-
project_fast = _text(commands_cfg.get("project_fast"))
|
|
1244
|
-
inferred_fast = _inferred_gate_commands(repo).get("project_fast", "")
|
|
1245
|
-
if not project_fast:
|
|
1246
|
-
replacement = (
|
|
1247
|
-
current_changed_gate
|
|
1248
|
-
if current_changed_gate and current_changed_gate not in {"git diff --check", "npm test"}
|
|
1249
|
-
else inferred_fast
|
|
1250
|
-
)
|
|
1251
|
-
commands_cfg["project_fast"] = replacement
|
|
1252
|
-
changed.append("commands.project_fast")
|
|
1253
|
-
|
|
1254
|
-
gate_cfg = cfg.setdefault("gate", {})
|
|
1255
|
-
if not isinstance(gate_cfg, dict):
|
|
1256
|
-
gate_cfg = {}
|
|
1257
|
-
cfg["gate"] = gate_cfg
|
|
1258
|
-
for key in ["default_scope", "fallback_scope", "no_change_scope"]:
|
|
1259
|
-
if _text(gate_cfg.get(key)).lower() != "changed":
|
|
1260
|
-
gate_cfg[key] = "changed"
|
|
1261
|
-
changed.append(f"gate.{key}")
|
|
1262
|
-
if _bool_config(gate_cfg.get("full_on_unknown"), False):
|
|
1263
|
-
gate_cfg["full_on_unknown"] = False
|
|
1264
|
-
changed.append("gate.full_on_unknown")
|
|
1265
|
-
if "full_on" in gate_cfg:
|
|
1266
|
-
del gate_cfg["full_on"]
|
|
1267
|
-
changed.append("gate.full_on")
|
|
1268
|
-
raw_rules = gate_cfg.get("rules")
|
|
1269
|
-
risk_cfg = cfg.setdefault("risk", {})
|
|
1270
|
-
if not isinstance(risk_cfg, dict):
|
|
1271
|
-
risk_cfg = {}
|
|
1272
|
-
cfg["risk"] = risk_cfg
|
|
1273
|
-
risk_rules = risk_cfg.setdefault("rules", [])
|
|
1274
|
-
if not isinstance(risk_rules, list):
|
|
1275
|
-
risk_rules = []
|
|
1276
|
-
risk_cfg["rules"] = risk_rules
|
|
1277
|
-
validation_cfg = cfg.setdefault("validation", {})
|
|
1278
|
-
if not isinstance(validation_cfg, dict):
|
|
1279
|
-
validation_cfg = {}
|
|
1280
|
-
cfg["validation"] = validation_cfg
|
|
1281
|
-
if _text(validation_cfg.get("on_unmapped")).lower() != "error":
|
|
1282
|
-
validation_cfg["on_unmapped"] = "error"
|
|
1283
|
-
changed.append("validation.on_unmapped")
|
|
1284
|
-
for key, default_value in [
|
|
1285
|
-
("max_command_seconds", int(_RECOMMENDED_FINAL_COMMAND_SECONDS)),
|
|
1286
|
-
("max_total_seconds", int(_RECOMMENDED_FINAL_TOTAL_SECONDS)),
|
|
1287
|
-
]:
|
|
1288
|
-
if key not in validation_cfg:
|
|
1289
|
-
validation_cfg[key] = default_value
|
|
1290
|
-
changed.append(f"validation.{key}")
|
|
1291
|
-
validation_routes = validation_cfg.setdefault("routes", [])
|
|
1292
|
-
if not isinstance(validation_routes, list):
|
|
1293
|
-
validation_routes = []
|
|
1294
|
-
validation_cfg["routes"] = validation_routes
|
|
1295
|
-
if isinstance(raw_rules, list):
|
|
1296
|
-
migrated_rules: list = []
|
|
1297
|
-
for index, rule in enumerate(raw_rules):
|
|
1298
|
-
if not isinstance(rule, dict):
|
|
1299
|
-
migrated_rules.append(rule)
|
|
1300
|
-
continue
|
|
1301
|
-
migrated_rule = {
|
|
1302
|
-
key: value
|
|
1303
|
-
for key, value in rule.items()
|
|
1304
|
-
if key in {"name", "paths", "profile", "review", "design"}
|
|
1305
|
-
}
|
|
1306
|
-
if migrated_rule and migrated_rule not in risk_rules:
|
|
1307
|
-
risk_rules.append(migrated_rule)
|
|
1308
|
-
changed.append(f"risk.rules[{len(risk_rules) - 1}]")
|
|
1309
|
-
legacy_commands = _as_list(rule.get("commands"))
|
|
1310
|
-
if legacy_commands and _as_list(rule.get("paths")):
|
|
1311
|
-
route = {
|
|
1312
|
-
"name": _text(rule.get("name")) or f"migrated-{index + 1}",
|
|
1313
|
-
"paths": _as_list(rule.get("paths")),
|
|
1314
|
-
"commands": [_command_name(item) for item in legacy_commands if _command_name(item)],
|
|
1315
|
-
}
|
|
1316
|
-
if route["commands"] and route not in validation_routes:
|
|
1317
|
-
validation_routes.append(route)
|
|
1318
|
-
changed.append(f"validation.routes[{len(validation_routes) - 1}]")
|
|
1319
|
-
if migrated_rules != raw_rules:
|
|
1320
|
-
gate_cfg["rules"] = []
|
|
1321
|
-
changed.append("gate.rules")
|
|
1257
|
+
def _flatten_config_paths(value: object, prefix: tuple[str, ...] = ()) -> list[str]:
|
|
1258
|
+
if not isinstance(value, dict) or not value:
|
|
1259
|
+
return [".".join(prefix)] if prefix else []
|
|
1260
|
+
result: list[str] = []
|
|
1261
|
+
for key, nested in value.items():
|
|
1262
|
+
result.extend(_flatten_config_paths(nested, (*prefix, str(key))))
|
|
1263
|
+
return result
|
|
1322
1264
|
|
|
1323
|
-
concurrency_cfg = cfg.setdefault("concurrency", {})
|
|
1324
|
-
if not isinstance(concurrency_cfg, dict):
|
|
1325
|
-
concurrency_cfg = {}
|
|
1326
|
-
cfg["concurrency"] = concurrency_cfg
|
|
1327
|
-
if _text(concurrency_cfg.get("isolation")).lower() != "adaptive":
|
|
1328
|
-
concurrency_cfg["isolation"] = "adaptive"
|
|
1329
|
-
changed.append("concurrency.isolation")
|
|
1330
1265
|
|
|
1331
|
-
|
|
1266
|
+
def _sha256_payload(payload: bytes) -> str:
|
|
1267
|
+
return hashlib.sha256(payload).hexdigest()
|
|
1332
1268
|
|
|
1333
1269
|
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
|
|
1270
|
+
_ARCHIVE_TARGET_ATTEMPTS = 64
|
|
1271
|
+
|
|
1272
|
+
|
|
1273
|
+
def _select_project_archive_target(
|
|
1274
|
+
repo: Path,
|
|
1275
|
+
preferred: str | Path,
|
|
1276
|
+
payload: bytes,
|
|
1277
|
+
*,
|
|
1278
|
+
legacy_digest_payload: bytes | None = None,
|
|
1279
|
+
) -> tuple[Path, bool]:
|
|
1280
|
+
"""Select an archive path without ever treating different bytes as archived."""
|
|
1281
|
+
preferred_rel = _safe_project_relative_path(preferred)
|
|
1282
|
+
payload_digest = hashlib.sha256(payload).hexdigest()
|
|
1283
|
+
legacy_digest = hashlib.sha256(
|
|
1284
|
+
payload if legacy_digest_payload is None else legacy_digest_payload
|
|
1285
|
+
).hexdigest()[:12]
|
|
1286
|
+
preferred_suffix = preferred_rel.suffix
|
|
1287
|
+
legacy_candidate = preferred_rel.with_name(
|
|
1288
|
+
f"{preferred_rel.stem}-{legacy_digest}{preferred_suffix}"
|
|
1289
|
+
)
|
|
1290
|
+
path_digest = hashlib.sha256(preferred_rel.as_posix().encode("utf-8")).hexdigest()[:12]
|
|
1291
|
+
compact_stem = f".autocoding-archive-{path_digest}-{payload_digest}"
|
|
1292
|
+
|
|
1293
|
+
candidates = [preferred_rel]
|
|
1337
1294
|
try:
|
|
1338
|
-
|
|
1339
|
-
|
|
1340
|
-
|
|
1341
|
-
|
|
1295
|
+
if len(os.fsencode(legacy_candidate.name)) <= 240:
|
|
1296
|
+
candidates.append(legacy_candidate)
|
|
1297
|
+
except UnicodeEncodeError:
|
|
1298
|
+
pass
|
|
1299
|
+
candidates.append(preferred_rel.with_name(f"{compact_stem}{preferred_suffix}"))
|
|
1300
|
+
candidates.extend(
|
|
1301
|
+
preferred_rel.with_name(f"{compact_stem}-{attempt}{preferred_suffix}")
|
|
1302
|
+
for attempt in range(2, _ARCHIVE_TARGET_ATTEMPTS + 1)
|
|
1303
|
+
)
|
|
1304
|
+
|
|
1305
|
+
seen: set[str] = set()
|
|
1306
|
+
for candidate in candidates:
|
|
1307
|
+
key = candidate.as_posix()
|
|
1308
|
+
if key in seen:
|
|
1309
|
+
continue
|
|
1310
|
+
seen.add(key)
|
|
1311
|
+
archived = _safe_read_project_file(repo, candidate)
|
|
1312
|
+
if archived is None:
|
|
1313
|
+
return candidate, True
|
|
1314
|
+
if archived == payload:
|
|
1315
|
+
return candidate, False
|
|
1316
|
+
raise APError(
|
|
1317
|
+
"Cannot allocate a collision-free project archive target without overwriting "
|
|
1318
|
+
f"different content: {preferred_rel.as_posix()}"
|
|
1319
|
+
)
|
|
1320
|
+
|
|
1342
1321
|
|
|
1322
|
+
def cmd_project_config_prepare(args: argparse.Namespace) -> None:
|
|
1323
|
+
repo = Path(args.repo).resolve()
|
|
1324
|
+
template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
|
|
1325
|
+
plan = _project_config_convergence_plan(repo, template)
|
|
1343
1326
|
write = bool(args.write)
|
|
1344
|
-
|
|
1327
|
+
current = plan["engineering_current"].encode("utf-8")
|
|
1328
|
+
engineering_output = plan["engineering_output"].encode("utf-8")
|
|
1329
|
+
overlay = plan["overlay_output"] or plan["overlay_current"]
|
|
1330
|
+
if overlay is None:
|
|
1331
|
+
raise APError("Project configuration prepare did not produce an overlay; no files were written.")
|
|
1332
|
+
finalize_required = bool(current and current != engineering_output)
|
|
1333
|
+
if finalize_required:
|
|
1334
|
+
template_cfg = parse_managed_config_payload(engineering_output)
|
|
1335
|
+
version = _text(_mapping(template_cfg.get("workflow")).get("skill_version")) or "current"
|
|
1336
|
+
archive_payload = (
|
|
1337
|
+
f"# Archived ENGINEERING.md before auto-coding-skill {version}\n\n"
|
|
1338
|
+
"Historical and non-authoritative. Project configuration was migrated to "
|
|
1339
|
+
"docs/project/auto-coding-skill.yaml.\n\n---\n\n"
|
|
1340
|
+
).encode("utf-8") + current
|
|
1341
|
+
_select_project_archive_target(
|
|
1342
|
+
repo,
|
|
1343
|
+
Path(".agents/archive/auto-coding-skill") / version / "docs/ENGINEERING.md",
|
|
1344
|
+
archive_payload,
|
|
1345
|
+
legacy_digest_payload=current,
|
|
1346
|
+
)
|
|
1345
1347
|
actions: list[dict] = []
|
|
1346
|
-
|
|
1347
|
-
|
|
1348
|
-
if path.exists() and not force:
|
|
1349
|
-
actions.append({"path": rel, "action": "exists"})
|
|
1350
|
-
continue
|
|
1351
|
-
action = "write" if write else "would-write"
|
|
1352
|
-
actions.append({"path": rel, "action": action})
|
|
1348
|
+
if plan["overlay_output"] is not None:
|
|
1349
|
+
actions.append({"action": "create", "path": _PROJECT_CONFIG_RELATIVE.as_posix()})
|
|
1353
1350
|
if write:
|
|
1354
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
1351
|
+
_safe_create_project_file(repo, _PROJECT_CONFIG_RELATIVE, overlay)
|
|
1352
|
+
if not current:
|
|
1353
|
+
actions.append({"action": "create", "path": "docs/ENGINEERING.md"})
|
|
1354
|
+
if write:
|
|
1355
|
+
_safe_write_project_file(repo, Path("docs/ENGINEERING.md"), engineering_output)
|
|
1356
|
+
elif finalize_required:
|
|
1357
|
+
actions.append({
|
|
1358
|
+
"action": "defer-replace",
|
|
1359
|
+
"path": "docs/ENGINEERING.md",
|
|
1360
|
+
"detail": "replace only after the effective-config runtime is installed",
|
|
1361
|
+
})
|
|
1362
|
+
result = {
|
|
1363
|
+
"mode": "write" if write else "plan",
|
|
1364
|
+
"actions": actions,
|
|
1365
|
+
"finalize_required": finalize_required,
|
|
1366
|
+
"engineering_before_sha256": _sha256_payload(current),
|
|
1367
|
+
"overlay_sha256": _sha256_payload(overlay),
|
|
1368
|
+
"template_sha256": _sha256_payload(engineering_output),
|
|
1369
|
+
}
|
|
1358
1370
|
if args.json:
|
|
1359
1371
|
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
1360
1372
|
return
|
|
1361
1373
|
for item in actions:
|
|
1362
|
-
print(f"[
|
|
1363
|
-
if not write:
|
|
1364
|
-
print("[scaffold] plan only; re-run with --write to create missing files")
|
|
1374
|
+
print(f"[project-config-prepare] {item['action']}: {item['path']}")
|
|
1365
1375
|
|
|
1366
1376
|
|
|
1367
|
-
def
|
|
1377
|
+
def cmd_project_config_finalize(args: argparse.Namespace) -> None:
|
|
1368
1378
|
repo = Path(args.repo).resolve()
|
|
1369
|
-
|
|
1379
|
+
template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
|
|
1380
|
+
template_payload = template.read_bytes()
|
|
1381
|
+
current = _safe_read_project_file(repo, Path("docs/ENGINEERING.md"), max_bytes=1024 * 1024)
|
|
1382
|
+
overlay = _safe_read_project_file(repo, _PROJECT_CONFIG_RELATIVE, max_bytes=128 * 1024)
|
|
1383
|
+
expected = {
|
|
1384
|
+
"engineering": _text(args.engineering_sha256),
|
|
1385
|
+
"overlay": _text(args.overlay_sha256),
|
|
1386
|
+
"template": _text(args.template_sha256),
|
|
1387
|
+
}
|
|
1388
|
+
if any(not re.fullmatch(r"[0-9a-f]{64}", value) for value in expected.values()):
|
|
1389
|
+
raise APError("Project configuration finalize requires valid SHA-256 bindings.")
|
|
1390
|
+
if current is None or overlay is None:
|
|
1391
|
+
raise APError("Prepared project configuration inputs are missing; no files were written.")
|
|
1392
|
+
actual = {
|
|
1393
|
+
"engineering": _sha256_payload(current),
|
|
1394
|
+
"overlay": _sha256_payload(overlay),
|
|
1395
|
+
"template": _sha256_payload(template_payload),
|
|
1396
|
+
}
|
|
1397
|
+
mismatched = [name for name in expected if expected[name] != actual[name]]
|
|
1398
|
+
if mismatched:
|
|
1399
|
+
raise APError(
|
|
1400
|
+
"Prepared project configuration changed before finalize; no files were written: "
|
|
1401
|
+
+ ", ".join(mismatched)
|
|
1402
|
+
)
|
|
1403
|
+
# Validate the final layers before replacing the legacy managed document.
|
|
1404
|
+
template_cfg = parse_managed_config_payload(template_payload)
|
|
1405
|
+
overrides = parse_project_overrides_payload(overlay)
|
|
1406
|
+
merge_project_config(template_cfg, overrides)
|
|
1407
|
+
version = _text(_mapping(template_cfg.get("workflow")).get("skill_version")) or "current"
|
|
1408
|
+
archive_payload = (
|
|
1409
|
+
f"# Archived ENGINEERING.md before auto-coding-skill {version}\n\n"
|
|
1410
|
+
"Historical and non-authoritative. Project configuration was migrated to "
|
|
1411
|
+
"docs/project/auto-coding-skill.yaml.\n\n---\n\n"
|
|
1412
|
+
).encode("utf-8") + current
|
|
1413
|
+
archive, archive_required = _select_project_archive_target(
|
|
1414
|
+
repo,
|
|
1415
|
+
Path(".agents/archive/auto-coding-skill") / version / "docs/ENGINEERING.md",
|
|
1416
|
+
archive_payload,
|
|
1417
|
+
legacy_digest_payload=current,
|
|
1418
|
+
)
|
|
1419
|
+
actions: list[dict] = []
|
|
1420
|
+
if archive_required:
|
|
1421
|
+
actions.append({"action": "archive", "path": archive.as_posix()})
|
|
1422
|
+
if args.write:
|
|
1423
|
+
_safe_create_project_file(repo, archive, archive_payload)
|
|
1424
|
+
if current != template_payload:
|
|
1425
|
+
actions.append({"action": "replace", "path": "docs/ENGINEERING.md"})
|
|
1426
|
+
if args.write:
|
|
1427
|
+
_safe_write_project_file(repo, Path("docs/ENGINEERING.md"), template_payload)
|
|
1428
|
+
result = {"mode": "write" if args.write else "plan", "actions": actions}
|
|
1429
|
+
if args.json:
|
|
1430
|
+
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
1431
|
+
return
|
|
1432
|
+
for item in actions:
|
|
1433
|
+
print(f"[project-config-finalize] {item['action']}: {item['path']}")
|
|
1370
1434
|
|
|
1371
|
-
planned_copies = [(templates / "ENGINEERING.md", repo / "docs" / "ENGINEERING.md")]
|
|
1372
|
-
for rel in _CORE_DOC_TEMPLATES:
|
|
1373
|
-
planned_copies.append((templates / "docs" / rel, repo / "docs" / rel))
|
|
1374
1435
|
|
|
1375
|
-
|
|
1376
|
-
planned_copies.append((templates / "bridges" / "AGENTS.md", repo / "AGENTS.md"))
|
|
1436
|
+
_PROJECT_ARTIFACT_ROOTS = tuple(Path(value) for value in PROJECT_OWNED_DOC_ROOTS)
|
|
1377
1437
|
|
|
1378
|
-
tools_dir = repo / "docs" / "tools" / "autopipeline"
|
|
1379
|
-
planned_copies.append((templates / "tools" / "ap.py", tools_dir / "ap.py"))
|
|
1380
1438
|
|
|
1381
|
-
|
|
1382
|
-
|
|
1383
|
-
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
|
|
1389
|
-
|
|
1390
|
-
|
|
1391
|
-
|
|
1392
|
-
)
|
|
1439
|
+
def _safe_project_relative_path(rel: str | Path) -> Path:
|
|
1440
|
+
value = Path(rel)
|
|
1441
|
+
if value.is_absolute() or not value.parts or any(part in {"", ".", ".."} for part in value.parts):
|
|
1442
|
+
raise APError(f"Unsafe project-relative path: {rel}")
|
|
1443
|
+
return value
|
|
1444
|
+
|
|
1445
|
+
|
|
1446
|
+
def _is_windows_reparse_point(metadata: os.stat_result) -> bool:
|
|
1447
|
+
attributes = int(getattr(metadata, "st_file_attributes", 0) or 0)
|
|
1448
|
+
reparse_flag = int(getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400))
|
|
1449
|
+
return stat.S_ISLNK(metadata.st_mode) or bool(attributes & reparse_flag)
|
|
1393
1450
|
|
|
1394
|
-
for src, dst in planned_copies:
|
|
1395
|
-
copy_tree(src, dst)
|
|
1396
1451
|
|
|
1397
|
-
|
|
1452
|
+
def _project_path_identity(metadata: os.stat_result) -> tuple[int, int]:
|
|
1453
|
+
return int(metadata.st_dev), int(metadata.st_ino)
|
|
1454
|
+
|
|
1455
|
+
|
|
1456
|
+
def _validate_windows_project_directories(
|
|
1457
|
+
relative: Path,
|
|
1458
|
+
directories: list[tuple[Path, tuple[int, int]]],
|
|
1459
|
+
) -> None:
|
|
1460
|
+
for directory, identity in directories:
|
|
1461
|
+
metadata = directory.lstat()
|
|
1462
|
+
if (
|
|
1463
|
+
_is_windows_reparse_point(metadata)
|
|
1464
|
+
or not stat.S_ISDIR(metadata.st_mode)
|
|
1465
|
+
or _project_path_identity(metadata) != identity
|
|
1466
|
+
):
|
|
1467
|
+
raise APError(f"Project path parent changed during its safety check: {relative}")
|
|
1468
|
+
|
|
1469
|
+
|
|
1470
|
+
def _windows_project_path_snapshot(
|
|
1471
|
+
repo: Path,
|
|
1472
|
+
relative: Path,
|
|
1473
|
+
*,
|
|
1474
|
+
create_parents: bool,
|
|
1475
|
+
) -> tuple[Path, list[tuple[Path, tuple[int, int]]], bool]:
|
|
1476
|
+
repo = Path(repo)
|
|
1477
|
+
repo_metadata = repo.lstat()
|
|
1478
|
+
if _is_windows_reparse_point(repo_metadata) or not stat.S_ISDIR(repo_metadata.st_mode):
|
|
1479
|
+
raise APError(f"Project repository root must be a real directory: {relative}")
|
|
1480
|
+
|
|
1481
|
+
directories = [(repo, _project_path_identity(repo_metadata))]
|
|
1482
|
+
current = repo
|
|
1483
|
+
for index, part in enumerate(relative.parts[:-1]):
|
|
1484
|
+
current = current / part
|
|
1485
|
+
if not os.path.lexists(current):
|
|
1486
|
+
if not create_parents:
|
|
1487
|
+
_validate_windows_project_directories(relative, directories)
|
|
1488
|
+
remaining = Path(*relative.parts[index + 1 :])
|
|
1489
|
+
return current / remaining, directories, False
|
|
1490
|
+
_validate_windows_project_directories(relative, directories)
|
|
1491
|
+
try:
|
|
1492
|
+
current.mkdir()
|
|
1493
|
+
except FileExistsError:
|
|
1494
|
+
# A concurrent creator is acceptable only when the result is
|
|
1495
|
+
# still a real directory and all previously checked parents
|
|
1496
|
+
# retain their identities.
|
|
1497
|
+
pass
|
|
1498
|
+
_validate_windows_project_directories(relative, directories)
|
|
1499
|
+
metadata = current.lstat()
|
|
1500
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
|
|
1501
|
+
raise APError(f"Project path component must be a real directory: {relative}")
|
|
1502
|
+
directories.append((current, _project_path_identity(metadata)))
|
|
1503
|
+
|
|
1504
|
+
_validate_windows_project_directories(relative, directories)
|
|
1505
|
+
return current / relative.parts[-1], directories, True
|
|
1506
|
+
|
|
1507
|
+
|
|
1508
|
+
def _fallback_safe_project_path(
|
|
1509
|
+
repo: Path,
|
|
1510
|
+
rel: str | Path,
|
|
1511
|
+
*,
|
|
1512
|
+
create_parents: bool = False,
|
|
1513
|
+
) -> Path:
|
|
1514
|
+
relative = _safe_project_relative_path(rel)
|
|
1515
|
+
try:
|
|
1516
|
+
target, _, _ = _windows_project_path_snapshot(
|
|
1517
|
+
Path(repo),
|
|
1518
|
+
relative,
|
|
1519
|
+
create_parents=create_parents,
|
|
1520
|
+
)
|
|
1521
|
+
return target
|
|
1522
|
+
except APError:
|
|
1523
|
+
raise
|
|
1524
|
+
except OSError as exc:
|
|
1525
|
+
raise APError(f"Cannot access project path safely: {relative}") from exc
|
|
1526
|
+
|
|
1527
|
+
|
|
1528
|
+
def _inject_project_file_parent_swap(repo: Path, relative: Path) -> None:
|
|
1529
|
+
if os.environ.get("AUTOCODING_TEST_MODE") != "1":
|
|
1530
|
+
return
|
|
1531
|
+
if os.environ.get("AUTOCODING_TEST_PROJECT_FILE_SWAP_PATH") != relative.as_posix():
|
|
1532
|
+
return
|
|
1533
|
+
if relative.parent == Path("."):
|
|
1534
|
+
raise APError("Project file parent-swap test requires a nested project path.")
|
|
1535
|
+
external = Path(os.environ.get("AUTOCODING_TEST_PROJECT_FILE_SWAP_EXTERNAL", ""))
|
|
1536
|
+
backup = Path(os.environ.get("AUTOCODING_TEST_PROJECT_FILE_SWAP_BACKUP", ""))
|
|
1537
|
+
target = Path(repo) / relative.parent
|
|
1538
|
+
if (
|
|
1539
|
+
not external.is_absolute()
|
|
1540
|
+
or not backup.is_absolute()
|
|
1541
|
+
or not external.is_dir()
|
|
1542
|
+
or external.is_symlink()
|
|
1543
|
+
or os.path.lexists(backup)
|
|
1544
|
+
):
|
|
1545
|
+
raise APError("Invalid project file parent-swap test fixture.")
|
|
1546
|
+
target.rename(backup)
|
|
1547
|
+
target.symlink_to(external, target_is_directory=True)
|
|
1548
|
+
|
|
1549
|
+
|
|
1550
|
+
@contextlib.contextmanager
|
|
1551
|
+
def _open_project_parent(repo: Path, rel: str | Path, *, create: bool = False):
|
|
1552
|
+
relative = _safe_project_relative_path(rel)
|
|
1553
|
+
directory_flags = os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0)
|
|
1554
|
+
descriptors: list[int] = []
|
|
1555
|
+
bindings: list[tuple[int, str, tuple[int, int]]] = []
|
|
1556
|
+
root_identity: tuple[int, int] | None = None
|
|
1557
|
+
|
|
1558
|
+
def validate_bindings() -> None:
|
|
1559
|
+
assert root_identity is not None
|
|
1560
|
+
root_metadata = Path(repo).lstat()
|
|
1561
|
+
if (
|
|
1562
|
+
_is_windows_reparse_point(root_metadata)
|
|
1563
|
+
or not stat.S_ISDIR(root_metadata.st_mode)
|
|
1564
|
+
or _project_path_identity(root_metadata) != root_identity
|
|
1565
|
+
):
|
|
1566
|
+
raise APError(f"Project repository root changed during its safety check: {relative}")
|
|
1567
|
+
for parent_fd, name, identity in bindings:
|
|
1568
|
+
metadata = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
|
|
1569
|
+
if (
|
|
1570
|
+
stat.S_ISLNK(metadata.st_mode)
|
|
1571
|
+
or not stat.S_ISDIR(metadata.st_mode)
|
|
1572
|
+
or _project_path_identity(metadata) != identity
|
|
1573
|
+
):
|
|
1574
|
+
raise APError(f"Project path parent changed during its safety check: {relative}")
|
|
1575
|
+
|
|
1576
|
+
try:
|
|
1577
|
+
current = os.open(repo, directory_flags)
|
|
1578
|
+
descriptors.append(current)
|
|
1579
|
+
root_metadata = os.fstat(current)
|
|
1580
|
+
if not stat.S_ISDIR(root_metadata.st_mode):
|
|
1581
|
+
raise APError(f"Project repository root must be a real directory: {relative}")
|
|
1582
|
+
root_identity = _project_path_identity(root_metadata)
|
|
1583
|
+
missing = False
|
|
1584
|
+
for part in relative.parts[:-1]:
|
|
1585
|
+
try:
|
|
1586
|
+
metadata = os.stat(part, dir_fd=current, follow_symlinks=False)
|
|
1587
|
+
except FileNotFoundError:
|
|
1588
|
+
if not create:
|
|
1589
|
+
missing = True
|
|
1590
|
+
break
|
|
1591
|
+
os.mkdir(part, 0o755, dir_fd=current)
|
|
1592
|
+
metadata = os.stat(part, dir_fd=current, follow_symlinks=False)
|
|
1593
|
+
if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
|
|
1594
|
+
raise APError(f"Project path component must be a real directory: {relative}")
|
|
1595
|
+
next_descriptor = os.open(part, directory_flags, dir_fd=current)
|
|
1596
|
+
opened = os.fstat(next_descriptor)
|
|
1597
|
+
identity = _project_path_identity(opened)
|
|
1598
|
+
if not stat.S_ISDIR(opened.st_mode) or identity != _project_path_identity(metadata):
|
|
1599
|
+
os.close(next_descriptor)
|
|
1600
|
+
raise APError(f"Project path parent changed during its safety check: {relative}")
|
|
1601
|
+
bindings.append((current, part, identity))
|
|
1602
|
+
descriptors.append(next_descriptor)
|
|
1603
|
+
current = next_descriptor
|
|
1604
|
+
_inject_project_file_parent_swap(Path(repo), relative)
|
|
1605
|
+
validate_bindings()
|
|
1606
|
+
yield (None if missing else current), relative.parts[-1]
|
|
1607
|
+
validate_bindings()
|
|
1608
|
+
except OSError as exc:
|
|
1609
|
+
raise APError(f"Cannot access project path safely: {relative}") from exc
|
|
1610
|
+
finally:
|
|
1611
|
+
for descriptor in reversed(descriptors):
|
|
1612
|
+
with contextlib.suppress(OSError):
|
|
1613
|
+
os.close(descriptor)
|
|
1614
|
+
|
|
1615
|
+
|
|
1616
|
+
def _safe_read_project_file(
|
|
1617
|
+
repo: Path,
|
|
1618
|
+
rel: str | Path,
|
|
1619
|
+
*,
|
|
1620
|
+
max_bytes: int | None = None,
|
|
1621
|
+
) -> bytes | None:
|
|
1622
|
+
relative = _safe_project_relative_path(rel)
|
|
1623
|
+
if max_bytes is not None and max_bytes <= 0:
|
|
1624
|
+
raise APError("max_bytes must be positive")
|
|
1625
|
+
if os.name == "nt":
|
|
1626
|
+
try:
|
|
1627
|
+
target, directories, parents_exist = _windows_project_path_snapshot(
|
|
1628
|
+
Path(repo),
|
|
1629
|
+
relative,
|
|
1630
|
+
create_parents=False,
|
|
1631
|
+
)
|
|
1632
|
+
if not parents_exist or not os.path.lexists(target):
|
|
1633
|
+
_validate_windows_project_directories(relative, directories)
|
|
1634
|
+
return None
|
|
1635
|
+
metadata = target.lstat()
|
|
1636
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
|
|
1637
|
+
raise APError(f"Project file must be a regular non-symlink file: {relative}")
|
|
1638
|
+
identity = _project_path_identity(metadata)
|
|
1639
|
+
if max_bytes is not None and metadata.st_size > max_bytes:
|
|
1640
|
+
raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
|
|
1641
|
+
with target.open("rb") as handle:
|
|
1642
|
+
opened = os.fstat(handle.fileno())
|
|
1643
|
+
checked = target.lstat()
|
|
1644
|
+
if (
|
|
1645
|
+
not stat.S_ISREG(opened.st_mode)
|
|
1646
|
+
or _project_path_identity(opened) != identity
|
|
1647
|
+
or _is_windows_reparse_point(checked)
|
|
1648
|
+
or not stat.S_ISREG(checked.st_mode)
|
|
1649
|
+
or _project_path_identity(checked) != identity
|
|
1650
|
+
):
|
|
1651
|
+
raise APError(f"Project file changed during its safety check: {relative}")
|
|
1652
|
+
_validate_windows_project_directories(relative, directories)
|
|
1653
|
+
payload = handle.read() if max_bytes is None else handle.read(max_bytes + 1)
|
|
1654
|
+
opened_after = os.fstat(handle.fileno())
|
|
1655
|
+
checked_after = target.lstat()
|
|
1656
|
+
if (
|
|
1657
|
+
not stat.S_ISREG(opened_after.st_mode)
|
|
1658
|
+
or _project_path_identity(opened_after) != identity
|
|
1659
|
+
or _is_windows_reparse_point(checked_after)
|
|
1660
|
+
or not stat.S_ISREG(checked_after.st_mode)
|
|
1661
|
+
or _project_path_identity(checked_after) != identity
|
|
1662
|
+
):
|
|
1663
|
+
raise APError(f"Project file changed while it was read: {relative}")
|
|
1664
|
+
_validate_windows_project_directories(relative, directories)
|
|
1665
|
+
if max_bytes is not None and len(payload) > max_bytes:
|
|
1666
|
+
raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
|
|
1667
|
+
return payload
|
|
1668
|
+
except APError:
|
|
1669
|
+
raise
|
|
1670
|
+
except OSError as exc:
|
|
1671
|
+
raise APError(f"Cannot read project file safely: {relative}") from exc
|
|
1672
|
+
with _open_project_parent(repo, relative) as (parent_fd, leaf):
|
|
1673
|
+
if parent_fd is None:
|
|
1674
|
+
return None
|
|
1675
|
+
descriptor = -1
|
|
1676
|
+
try:
|
|
1677
|
+
descriptor = os.open(leaf, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0), dir_fd=parent_fd)
|
|
1678
|
+
except FileNotFoundError:
|
|
1679
|
+
return None
|
|
1680
|
+
except OSError as exc:
|
|
1681
|
+
raise APError(f"Project file must be a regular non-symlink file: {relative}") from exc
|
|
1682
|
+
try:
|
|
1683
|
+
metadata = os.fstat(descriptor)
|
|
1684
|
+
if not stat.S_ISREG(metadata.st_mode):
|
|
1685
|
+
raise APError(f"Project file must be a regular non-symlink file: {relative}")
|
|
1686
|
+
if max_bytes is not None and metadata.st_size > max_bytes:
|
|
1687
|
+
raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
|
|
1688
|
+
with os.fdopen(descriptor, "rb") as handle:
|
|
1689
|
+
descriptor = -1
|
|
1690
|
+
payload = handle.read() if max_bytes is None else handle.read(max_bytes + 1)
|
|
1691
|
+
if max_bytes is not None and len(payload) > max_bytes:
|
|
1692
|
+
raise APError(f"Project file exceeds {max_bytes} bytes: {relative}")
|
|
1693
|
+
return payload
|
|
1694
|
+
finally:
|
|
1695
|
+
if descriptor >= 0:
|
|
1696
|
+
os.close(descriptor)
|
|
1697
|
+
|
|
1698
|
+
|
|
1699
|
+
@contextlib.contextmanager
|
|
1700
|
+
def _open_project_directory(repo: Path, rel: str | Path):
|
|
1701
|
+
relative = _safe_project_relative_path(rel)
|
|
1702
|
+
if os.name == "nt":
|
|
1703
|
+
try:
|
|
1704
|
+
target, directories, complete = _windows_project_path_snapshot(
|
|
1705
|
+
Path(repo),
|
|
1706
|
+
relative,
|
|
1707
|
+
create_parents=False,
|
|
1708
|
+
)
|
|
1709
|
+
except OSError as exc:
|
|
1710
|
+
raise APError(f"Cannot access project directory safely: {relative}") from exc
|
|
1711
|
+
if not complete or not os.path.lexists(target):
|
|
1712
|
+
yield None
|
|
1713
|
+
return
|
|
1714
|
+
metadata = target.lstat()
|
|
1715
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
|
|
1716
|
+
raise APError(f"Project directory must be a real directory: {relative}")
|
|
1717
|
+
identity = _project_path_identity(metadata)
|
|
1718
|
+
_validate_windows_project_directories(relative, directories)
|
|
1719
|
+
try:
|
|
1720
|
+
yield target
|
|
1721
|
+
finally:
|
|
1722
|
+
try:
|
|
1723
|
+
checked = target.lstat()
|
|
1724
|
+
_validate_windows_project_directories(relative, directories)
|
|
1725
|
+
except OSError as exc:
|
|
1726
|
+
raise APError(f"Project directory changed during its safety check: {relative}") from exc
|
|
1727
|
+
if (
|
|
1728
|
+
_is_windows_reparse_point(checked)
|
|
1729
|
+
or not stat.S_ISDIR(checked.st_mode)
|
|
1730
|
+
or _project_path_identity(checked) != identity
|
|
1731
|
+
):
|
|
1732
|
+
raise APError(f"Project directory changed during its safety check: {relative}")
|
|
1733
|
+
return
|
|
1734
|
+
with _open_project_parent(repo, relative) as (parent_fd, leaf):
|
|
1735
|
+
if parent_fd is None:
|
|
1736
|
+
yield None
|
|
1737
|
+
return
|
|
1738
|
+
descriptor = -1
|
|
1739
|
+
try:
|
|
1740
|
+
descriptor = os.open(
|
|
1741
|
+
leaf,
|
|
1742
|
+
os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
|
|
1743
|
+
dir_fd=parent_fd,
|
|
1744
|
+
)
|
|
1745
|
+
except FileNotFoundError:
|
|
1746
|
+
yield None
|
|
1747
|
+
return
|
|
1748
|
+
except OSError as exc:
|
|
1749
|
+
raise APError(f"Project directory must be a real directory: {relative}") from exc
|
|
1750
|
+
try:
|
|
1751
|
+
metadata = os.fstat(descriptor)
|
|
1752
|
+
if not stat.S_ISDIR(metadata.st_mode):
|
|
1753
|
+
raise APError(f"Project directory must be a real directory: {relative}")
|
|
1754
|
+
yield descriptor
|
|
1755
|
+
finally:
|
|
1756
|
+
if descriptor >= 0:
|
|
1757
|
+
os.close(descriptor)
|
|
1758
|
+
|
|
1759
|
+
|
|
1760
|
+
def _safe_write_project_file(repo: Path, rel: str | Path, payload: bytes) -> None:
|
|
1761
|
+
relative = _safe_project_relative_path(rel)
|
|
1762
|
+
if os.name == "nt":
|
|
1763
|
+
temporary: Path | None = None
|
|
1764
|
+
try:
|
|
1765
|
+
target, directories, _ = _windows_project_path_snapshot(
|
|
1766
|
+
Path(repo),
|
|
1767
|
+
relative,
|
|
1768
|
+
create_parents=True,
|
|
1769
|
+
)
|
|
1770
|
+
_inject_project_file_parent_swap(Path(repo), relative)
|
|
1771
|
+
target_identity: tuple[int, int] | None = None
|
|
1772
|
+
if os.path.lexists(target):
|
|
1773
|
+
metadata = target.lstat()
|
|
1774
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
|
|
1775
|
+
raise APError(f"Project file must be a regular non-symlink file: {relative}")
|
|
1776
|
+
target_identity = _project_path_identity(metadata)
|
|
1777
|
+
_validate_windows_project_directories(relative, directories)
|
|
1778
|
+
|
|
1779
|
+
temporary = target.with_name(f".{target.name}.autocoding-{uuid.uuid4().hex}")
|
|
1780
|
+
with temporary.open("xb") as handle:
|
|
1781
|
+
opened = os.fstat(handle.fileno())
|
|
1782
|
+
checked = temporary.lstat()
|
|
1783
|
+
temporary_identity = _project_path_identity(opened)
|
|
1784
|
+
if (
|
|
1785
|
+
not stat.S_ISREG(opened.st_mode)
|
|
1786
|
+
or _is_windows_reparse_point(checked)
|
|
1787
|
+
or not stat.S_ISREG(checked.st_mode)
|
|
1788
|
+
or _project_path_identity(checked) != temporary_identity
|
|
1789
|
+
):
|
|
1790
|
+
raise APError(f"Temporary project file is unsafe: {relative}")
|
|
1791
|
+
_validate_windows_project_directories(relative, directories)
|
|
1792
|
+
handle.write(payload)
|
|
1793
|
+
handle.flush()
|
|
1794
|
+
os.fsync(handle.fileno())
|
|
1795
|
+
opened_after = os.fstat(handle.fileno())
|
|
1796
|
+
checked_after = temporary.lstat()
|
|
1797
|
+
if (
|
|
1798
|
+
not stat.S_ISREG(opened_after.st_mode)
|
|
1799
|
+
or _project_path_identity(opened_after) != temporary_identity
|
|
1800
|
+
or _is_windows_reparse_point(checked_after)
|
|
1801
|
+
or not stat.S_ISREG(checked_after.st_mode)
|
|
1802
|
+
or _project_path_identity(checked_after) != temporary_identity
|
|
1803
|
+
):
|
|
1804
|
+
raise APError(f"Temporary project file changed while writing: {relative}")
|
|
1805
|
+
_validate_windows_project_directories(relative, directories)
|
|
1806
|
+
|
|
1807
|
+
if target_identity is None:
|
|
1808
|
+
if os.path.lexists(target):
|
|
1809
|
+
raise APError(f"Project file appeared while writing: {relative}")
|
|
1810
|
+
else:
|
|
1811
|
+
checked_target = target.lstat()
|
|
1812
|
+
if (
|
|
1813
|
+
_is_windows_reparse_point(checked_target)
|
|
1814
|
+
or not stat.S_ISREG(checked_target.st_mode)
|
|
1815
|
+
or _project_path_identity(checked_target) != target_identity
|
|
1816
|
+
):
|
|
1817
|
+
raise APError(f"Project file changed while writing: {relative}")
|
|
1818
|
+
_validate_windows_project_directories(relative, directories)
|
|
1819
|
+
os.replace(temporary, target)
|
|
1820
|
+
replaced = target.lstat()
|
|
1821
|
+
if (
|
|
1822
|
+
_is_windows_reparse_point(replaced)
|
|
1823
|
+
or not stat.S_ISREG(replaced.st_mode)
|
|
1824
|
+
or _project_path_identity(replaced) != temporary_identity
|
|
1825
|
+
):
|
|
1826
|
+
raise APError(f"Project file changed after replacement: {relative}")
|
|
1827
|
+
_validate_windows_project_directories(relative, directories)
|
|
1828
|
+
except APError:
|
|
1829
|
+
if temporary is not None:
|
|
1830
|
+
with contextlib.suppress(OSError):
|
|
1831
|
+
temporary.unlink()
|
|
1832
|
+
raise
|
|
1833
|
+
except OSError as exc:
|
|
1834
|
+
if temporary is not None:
|
|
1835
|
+
with contextlib.suppress(OSError):
|
|
1836
|
+
temporary.unlink()
|
|
1837
|
+
raise APError(f"Cannot write project file safely: {relative}") from exc
|
|
1838
|
+
return
|
|
1839
|
+
with _open_project_parent(repo, relative, create=True) as (parent_fd, leaf):
|
|
1840
|
+
assert parent_fd is not None
|
|
1841
|
+
temporary = f".{leaf}.autocoding-{uuid.uuid4().hex}"
|
|
1842
|
+
descriptor = -1
|
|
1843
|
+
try:
|
|
1844
|
+
descriptor = os.open(
|
|
1845
|
+
temporary,
|
|
1846
|
+
os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
|
|
1847
|
+
0o644,
|
|
1848
|
+
dir_fd=parent_fd,
|
|
1849
|
+
)
|
|
1850
|
+
with os.fdopen(descriptor, "wb") as handle:
|
|
1851
|
+
descriptor = -1
|
|
1852
|
+
handle.write(payload)
|
|
1853
|
+
handle.flush()
|
|
1854
|
+
os.fsync(handle.fileno())
|
|
1855
|
+
os.replace(temporary, leaf, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
|
|
1856
|
+
except OSError as exc:
|
|
1857
|
+
with contextlib.suppress(OSError):
|
|
1858
|
+
os.unlink(temporary, dir_fd=parent_fd)
|
|
1859
|
+
raise APError(f"Cannot write project file safely: {relative}") from exc
|
|
1860
|
+
finally:
|
|
1861
|
+
if descriptor >= 0:
|
|
1862
|
+
os.close(descriptor)
|
|
1863
|
+
|
|
1864
|
+
|
|
1865
|
+
def _safe_create_project_file(repo: Path, rel: str | Path, payload: bytes) -> None:
|
|
1866
|
+
"""Atomically publish a new project file without replacing a concurrent creator."""
|
|
1867
|
+
relative = _safe_project_relative_path(rel)
|
|
1868
|
+
if os.name == "nt":
|
|
1869
|
+
temporary: Path | None = None
|
|
1870
|
+
try:
|
|
1871
|
+
target, directories, _ = _windows_project_path_snapshot(
|
|
1872
|
+
Path(repo),
|
|
1873
|
+
relative,
|
|
1874
|
+
create_parents=True,
|
|
1875
|
+
)
|
|
1876
|
+
_inject_project_file_parent_swap(Path(repo), relative)
|
|
1877
|
+
_validate_windows_project_directories(relative, directories)
|
|
1878
|
+
temporary = target.with_name(f".{target.name}.autocoding-{uuid.uuid4().hex}")
|
|
1879
|
+
with temporary.open("xb") as handle:
|
|
1880
|
+
handle.write(payload)
|
|
1881
|
+
handle.flush()
|
|
1882
|
+
os.fsync(handle.fileno())
|
|
1883
|
+
temporary_metadata = os.fstat(handle.fileno())
|
|
1884
|
+
checked_temporary = temporary.lstat()
|
|
1885
|
+
temporary_identity = _project_path_identity(temporary_metadata)
|
|
1886
|
+
if (
|
|
1887
|
+
not stat.S_ISREG(temporary_metadata.st_mode)
|
|
1888
|
+
or _is_windows_reparse_point(checked_temporary)
|
|
1889
|
+
or not stat.S_ISREG(checked_temporary.st_mode)
|
|
1890
|
+
or _project_path_identity(checked_temporary) != temporary_identity
|
|
1891
|
+
):
|
|
1892
|
+
raise APError(f"Temporary project file is unsafe: {relative}")
|
|
1893
|
+
_validate_windows_project_directories(relative, directories)
|
|
1894
|
+
try:
|
|
1895
|
+
os.link(temporary, target, follow_symlinks=False)
|
|
1896
|
+
except FileExistsError as exc:
|
|
1897
|
+
raise APError(f"Project file appeared before create-only publish: {relative}") from exc
|
|
1898
|
+
checked_target = target.lstat()
|
|
1899
|
+
if (
|
|
1900
|
+
_is_windows_reparse_point(checked_target)
|
|
1901
|
+
or not stat.S_ISREG(checked_target.st_mode)
|
|
1902
|
+
or _project_path_identity(checked_target) != temporary_identity
|
|
1903
|
+
):
|
|
1904
|
+
raise APError(f"Project file changed during create-only publish: {relative}")
|
|
1905
|
+
_validate_windows_project_directories(relative, directories)
|
|
1906
|
+
except APError:
|
|
1907
|
+
raise
|
|
1908
|
+
except OSError as exc:
|
|
1909
|
+
raise APError(f"Cannot create project file safely: {relative}") from exc
|
|
1910
|
+
finally:
|
|
1911
|
+
if temporary is not None:
|
|
1912
|
+
with contextlib.suppress(OSError):
|
|
1913
|
+
temporary.unlink()
|
|
1914
|
+
return
|
|
1915
|
+
|
|
1916
|
+
with _open_project_parent(repo, relative, create=True) as (parent_fd, leaf):
|
|
1917
|
+
assert parent_fd is not None
|
|
1918
|
+
temporary = f".{leaf}.autocoding-{uuid.uuid4().hex}"
|
|
1919
|
+
descriptor = -1
|
|
1920
|
+
try:
|
|
1921
|
+
descriptor = os.open(
|
|
1922
|
+
temporary,
|
|
1923
|
+
os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
|
|
1924
|
+
0o644,
|
|
1925
|
+
dir_fd=parent_fd,
|
|
1926
|
+
)
|
|
1927
|
+
with os.fdopen(descriptor, "wb") as handle:
|
|
1928
|
+
descriptor = -1
|
|
1929
|
+
handle.write(payload)
|
|
1930
|
+
handle.flush()
|
|
1931
|
+
os.fsync(handle.fileno())
|
|
1932
|
+
temporary_metadata = os.stat(
|
|
1933
|
+
temporary,
|
|
1934
|
+
dir_fd=parent_fd,
|
|
1935
|
+
follow_symlinks=False,
|
|
1936
|
+
)
|
|
1937
|
+
if stat.S_ISLNK(temporary_metadata.st_mode) or not stat.S_ISREG(
|
|
1938
|
+
temporary_metadata.st_mode
|
|
1939
|
+
):
|
|
1940
|
+
raise APError(f"Temporary project file is unsafe: {relative}")
|
|
1941
|
+
temporary_identity = _project_path_identity(temporary_metadata)
|
|
1942
|
+
try:
|
|
1943
|
+
os.link(
|
|
1944
|
+
temporary,
|
|
1945
|
+
leaf,
|
|
1946
|
+
src_dir_fd=parent_fd,
|
|
1947
|
+
dst_dir_fd=parent_fd,
|
|
1948
|
+
follow_symlinks=False,
|
|
1949
|
+
)
|
|
1950
|
+
except FileExistsError as exc:
|
|
1951
|
+
raise APError(f"Project file appeared before create-only publish: {relative}") from exc
|
|
1952
|
+
published = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
|
|
1953
|
+
if (
|
|
1954
|
+
stat.S_ISLNK(published.st_mode)
|
|
1955
|
+
or not stat.S_ISREG(published.st_mode)
|
|
1956
|
+
or _project_path_identity(published) != temporary_identity
|
|
1957
|
+
):
|
|
1958
|
+
raise APError(f"Project file changed during create-only publish: {relative}")
|
|
1959
|
+
except APError:
|
|
1960
|
+
raise
|
|
1961
|
+
except OSError as exc:
|
|
1962
|
+
raise APError(f"Cannot create project file safely: {relative}") from exc
|
|
1963
|
+
finally:
|
|
1964
|
+
if descriptor >= 0:
|
|
1965
|
+
os.close(descriptor)
|
|
1966
|
+
with contextlib.suppress(OSError):
|
|
1967
|
+
os.unlink(temporary, dir_fd=parent_fd)
|
|
1968
|
+
|
|
1969
|
+
|
|
1970
|
+
def _safe_chmod_project_file(repo: Path, rel: str | Path, mode: int) -> None:
|
|
1971
|
+
relative = _safe_project_relative_path(rel)
|
|
1972
|
+
if mode < 0 or mode > 0o777:
|
|
1973
|
+
raise APError(f"Project file mode must be between 000 and 777: {relative}")
|
|
1974
|
+
if os.name == "nt":
|
|
1975
|
+
try:
|
|
1976
|
+
target, directories, complete = _windows_project_path_snapshot(
|
|
1977
|
+
Path(repo),
|
|
1978
|
+
relative,
|
|
1979
|
+
create_parents=False,
|
|
1980
|
+
)
|
|
1981
|
+
_inject_project_file_parent_swap(Path(repo), relative)
|
|
1982
|
+
if not complete or not os.path.lexists(target):
|
|
1983
|
+
raise APError(f"Project file is missing: {relative}")
|
|
1984
|
+
metadata = target.lstat()
|
|
1985
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
|
|
1986
|
+
raise APError(f"Project file must be a regular non-symlink file: {relative}")
|
|
1987
|
+
identity = _project_path_identity(metadata)
|
|
1988
|
+
_validate_windows_project_directories(relative, directories)
|
|
1989
|
+
os.chmod(target, mode, follow_symlinks=False)
|
|
1990
|
+
checked = target.lstat()
|
|
1991
|
+
_validate_windows_project_directories(relative, directories)
|
|
1992
|
+
if (
|
|
1993
|
+
_is_windows_reparse_point(checked)
|
|
1994
|
+
or not stat.S_ISREG(checked.st_mode)
|
|
1995
|
+
or _project_path_identity(checked) != identity
|
|
1996
|
+
):
|
|
1997
|
+
raise APError(f"Project file changed while setting its mode: {relative}")
|
|
1998
|
+
except APError:
|
|
1999
|
+
raise
|
|
2000
|
+
except OSError as exc:
|
|
2001
|
+
raise APError(f"Cannot set project file mode safely: {relative}") from exc
|
|
2002
|
+
return
|
|
2003
|
+
|
|
2004
|
+
with _open_project_parent(repo, relative) as (parent_fd, leaf):
|
|
2005
|
+
if parent_fd is None:
|
|
2006
|
+
raise APError(f"Project file is missing: {relative}")
|
|
2007
|
+
descriptor = -1
|
|
2008
|
+
try:
|
|
2009
|
+
descriptor = os.open(
|
|
2010
|
+
leaf,
|
|
2011
|
+
os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0),
|
|
2012
|
+
dir_fd=parent_fd,
|
|
2013
|
+
)
|
|
2014
|
+
metadata = os.fstat(descriptor)
|
|
2015
|
+
if not stat.S_ISREG(metadata.st_mode):
|
|
2016
|
+
raise APError(f"Project file must be a regular non-symlink file: {relative}")
|
|
2017
|
+
os.fchmod(descriptor, mode)
|
|
2018
|
+
checked = os.fstat(descriptor)
|
|
2019
|
+
if _project_path_identity(checked) != _project_path_identity(metadata):
|
|
2020
|
+
raise APError(f"Project file changed while setting its mode: {relative}")
|
|
2021
|
+
except APError:
|
|
2022
|
+
raise
|
|
2023
|
+
except OSError as exc:
|
|
2024
|
+
raise APError(f"Cannot set project file mode safely: {relative}") from exc
|
|
2025
|
+
finally:
|
|
2026
|
+
if descriptor >= 0:
|
|
2027
|
+
os.close(descriptor)
|
|
2028
|
+
|
|
2029
|
+
|
|
2030
|
+
_INTERNAL_PROJECT_FILE_MAX_BYTES = 32 * 1024 * 1024
|
|
2031
|
+
_INTERNAL_PROJECT_CHMOD_MAX_BYTES = 1024 * 1024
|
|
2032
|
+
_INTERNAL_PROJECT_CHMOD_MAX_ENTRIES = 4096
|
|
2033
|
+
|
|
2034
|
+
|
|
2035
|
+
def cmd_project_file_safe(args: argparse.Namespace) -> None:
|
|
2036
|
+
repo = Path(args.repo).resolve()
|
|
2037
|
+
operation = _text(args.operation).lower()
|
|
2038
|
+
relative: Path | None = None
|
|
2039
|
+
if operation != "chmod-batch":
|
|
2040
|
+
relative = _safe_project_relative_path(args.path)
|
|
2041
|
+
if operation in {"write", "create"}:
|
|
2042
|
+
assert relative is not None
|
|
2043
|
+
payload = sys.stdin.buffer.read(_INTERNAL_PROJECT_FILE_MAX_BYTES + 1)
|
|
2044
|
+
if len(payload) > _INTERNAL_PROJECT_FILE_MAX_BYTES:
|
|
2045
|
+
raise APError(
|
|
2046
|
+
f"Internal project file payload exceeds {_INTERNAL_PROJECT_FILE_MAX_BYTES} bytes: {relative}"
|
|
2047
|
+
)
|
|
2048
|
+
if operation == "create":
|
|
2049
|
+
_safe_create_project_file(repo, relative, payload)
|
|
2050
|
+
else:
|
|
2051
|
+
_safe_write_project_file(repo, relative, payload)
|
|
2052
|
+
if _text(args.mode):
|
|
2053
|
+
try:
|
|
2054
|
+
mode = int(_text(args.mode), 8)
|
|
2055
|
+
except ValueError as exc:
|
|
2056
|
+
raise APError("Internal project write requires an octal --mode") from exc
|
|
2057
|
+
_safe_chmod_project_file(repo, relative, mode)
|
|
2058
|
+
elif operation == "chmod":
|
|
2059
|
+
assert relative is not None
|
|
2060
|
+
try:
|
|
2061
|
+
mode = int(_text(args.mode), 8)
|
|
2062
|
+
except ValueError as exc:
|
|
2063
|
+
raise APError("Internal project chmod requires an octal --mode") from exc
|
|
2064
|
+
_safe_chmod_project_file(repo, relative, mode)
|
|
2065
|
+
elif operation == "chmod-batch":
|
|
2066
|
+
payload = sys.stdin.buffer.read(_INTERNAL_PROJECT_CHMOD_MAX_BYTES + 1)
|
|
2067
|
+
if len(payload) > _INTERNAL_PROJECT_CHMOD_MAX_BYTES:
|
|
2068
|
+
raise APError("Internal project chmod batch exceeds its size limit")
|
|
2069
|
+
try:
|
|
2070
|
+
entries = json.loads(payload.decode("utf-8"))
|
|
2071
|
+
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
|
|
2072
|
+
raise APError("Internal project chmod batch must be valid UTF-8 JSON") from exc
|
|
2073
|
+
if not isinstance(entries, list) or len(entries) > _INTERNAL_PROJECT_CHMOD_MAX_ENTRIES:
|
|
2074
|
+
raise APError("Internal project chmod batch has an invalid entry count")
|
|
2075
|
+
mutations: list[tuple[Path, int]] = []
|
|
2076
|
+
for index, entry in enumerate(entries):
|
|
2077
|
+
if not isinstance(entry, dict) or set(entry) != {"path", "mode"}:
|
|
2078
|
+
raise APError(f"Internal project chmod batch entry {index} is invalid")
|
|
2079
|
+
mode_text = entry.get("mode")
|
|
2080
|
+
path_text = entry.get("path")
|
|
2081
|
+
if not isinstance(mode_text, str) or not re.fullmatch(r"[0-7]{3}", mode_text):
|
|
2082
|
+
raise APError(f"Internal project chmod batch entry {index} has an invalid mode")
|
|
2083
|
+
if not isinstance(path_text, str) or not path_text:
|
|
2084
|
+
raise APError(f"Internal project chmod batch entry {index} has an invalid path")
|
|
2085
|
+
mutations.append(
|
|
2086
|
+
(_safe_project_relative_path(path_text), int(mode_text, 8))
|
|
2087
|
+
)
|
|
2088
|
+
for mutation_path, mutation_mode in mutations:
|
|
2089
|
+
_safe_chmod_project_file(repo, mutation_path, mutation_mode)
|
|
2090
|
+
else:
|
|
2091
|
+
raise APError(f"Unsupported internal project file operation: {operation}")
|
|
2092
|
+
if args.json:
|
|
2093
|
+
result = {"operation": operation, "ok": True}
|
|
2094
|
+
if relative is not None:
|
|
2095
|
+
result["path"] = relative.as_posix()
|
|
2096
|
+
else:
|
|
2097
|
+
result["entry_count"] = len(mutations)
|
|
2098
|
+
print(json.dumps(result))
|
|
2099
|
+
|
|
2100
|
+
|
|
2101
|
+
def _directory_handle_identity(handle: int | Path) -> tuple[int, int]:
|
|
2102
|
+
metadata = os.fstat(handle) if isinstance(handle, int) else handle.lstat()
|
|
2103
|
+
if (
|
|
2104
|
+
not stat.S_ISDIR(metadata.st_mode)
|
|
2105
|
+
or (not isinstance(handle, int) and _is_windows_reparse_point(metadata))
|
|
2106
|
+
):
|
|
2107
|
+
raise APError("Install I/O requires real project directories.")
|
|
2108
|
+
return _project_path_identity(metadata)
|
|
2109
|
+
|
|
2110
|
+
|
|
2111
|
+
def _safe_ensure_project_directory(repo: Path, rel: str | Path) -> None:
|
|
2112
|
+
relative = _safe_project_relative_path(rel)
|
|
2113
|
+
if os.name == "nt":
|
|
2114
|
+
try:
|
|
2115
|
+
target, directories, _ = _windows_project_path_snapshot(
|
|
2116
|
+
Path(repo),
|
|
2117
|
+
relative,
|
|
2118
|
+
create_parents=True,
|
|
2119
|
+
)
|
|
2120
|
+
_validate_windows_project_directories(relative, directories)
|
|
2121
|
+
try:
|
|
2122
|
+
target.mkdir()
|
|
2123
|
+
except FileExistsError:
|
|
2124
|
+
pass
|
|
2125
|
+
metadata = target.lstat()
|
|
2126
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
|
|
2127
|
+
raise APError(f"Project directory must be a real directory: {relative}")
|
|
2128
|
+
_validate_windows_project_directories(relative, directories)
|
|
2129
|
+
except APError:
|
|
2130
|
+
raise
|
|
2131
|
+
except OSError as exc:
|
|
2132
|
+
raise APError(f"Cannot create project directory safely: {relative}") from exc
|
|
2133
|
+
return
|
|
2134
|
+
with _open_project_parent(repo, relative, create=True) as (parent_fd, leaf):
|
|
2135
|
+
assert parent_fd is not None
|
|
2136
|
+
try:
|
|
2137
|
+
os.mkdir(leaf, 0o755, dir_fd=parent_fd)
|
|
2138
|
+
except FileExistsError:
|
|
2139
|
+
pass
|
|
2140
|
+
metadata = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
|
|
2141
|
+
if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
|
|
2142
|
+
raise APError(f"Project directory must be a real directory: {relative}")
|
|
2143
|
+
|
|
2144
|
+
|
|
2145
|
+
def _require_bound_project_directory(
|
|
2146
|
+
repo: Path,
|
|
2147
|
+
relative: Path,
|
|
2148
|
+
handle: int | Path,
|
|
2149
|
+
identity: tuple[int, int],
|
|
2150
|
+
) -> None:
|
|
2151
|
+
opened = os.fstat(handle) if isinstance(handle, int) else handle.lstat()
|
|
2152
|
+
if not stat.S_ISDIR(opened.st_mode) or _project_path_identity(opened) != identity:
|
|
2153
|
+
raise APError(f"Install I/O directory handle changed: {relative}")
|
|
2154
|
+
target = repo / relative
|
|
2155
|
+
try:
|
|
2156
|
+
current = target.lstat()
|
|
2157
|
+
except OSError as exc:
|
|
2158
|
+
raise APError(f"Install I/O project parent changed: {relative}") from exc
|
|
2159
|
+
if (
|
|
2160
|
+
_is_windows_reparse_point(current)
|
|
2161
|
+
or not stat.S_ISDIR(current.st_mode)
|
|
2162
|
+
or _project_path_identity(current) != identity
|
|
2163
|
+
):
|
|
2164
|
+
raise APError(f"Install I/O project parent changed: {relative}")
|
|
2165
|
+
|
|
2166
|
+
|
|
2167
|
+
def _inject_install_io_parent_swap(repo: Path, phase: str) -> None:
|
|
2168
|
+
if os.environ.get("AUTOCODING_TEST_MODE") != "1":
|
|
2169
|
+
return
|
|
2170
|
+
if os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_PHASE") != phase:
|
|
2171
|
+
return
|
|
2172
|
+
relative_text = os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_PARENT", "")
|
|
2173
|
+
external_text = os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_EXTERNAL", "")
|
|
2174
|
+
backup_text = os.environ.get("AUTOCODING_TEST_INSTALL_IO_SWAP_BACKUP", "")
|
|
2175
|
+
relative = _safe_project_relative_path(relative_text)
|
|
2176
|
+
target = repo / relative
|
|
2177
|
+
external = Path(external_text)
|
|
2178
|
+
backup = Path(backup_text)
|
|
2179
|
+
if (
|
|
2180
|
+
not external.is_absolute()
|
|
2181
|
+
or not backup.is_absolute()
|
|
2182
|
+
or not external.is_dir()
|
|
2183
|
+
or external.is_symlink()
|
|
2184
|
+
or os.path.lexists(backup)
|
|
2185
|
+
):
|
|
2186
|
+
raise APError("Invalid install I/O parent-swap test fixture.")
|
|
2187
|
+
target.rename(backup)
|
|
2188
|
+
target.symlink_to(external, target_is_directory=True)
|
|
2189
|
+
|
|
2190
|
+
|
|
2191
|
+
def _open_directory_at(parent_fd: int, name: str) -> int:
|
|
2192
|
+
descriptor = os.open(
|
|
2193
|
+
name,
|
|
2194
|
+
os.O_RDONLY | getattr(os, "O_DIRECTORY", 0) | getattr(os, "O_NOFOLLOW", 0),
|
|
2195
|
+
dir_fd=parent_fd,
|
|
2196
|
+
)
|
|
2197
|
+
metadata = os.fstat(descriptor)
|
|
2198
|
+
if not stat.S_ISDIR(metadata.st_mode):
|
|
2199
|
+
os.close(descriptor)
|
|
2200
|
+
raise APError(f"Install I/O path must be a real directory: {name}")
|
|
2201
|
+
return descriptor
|
|
2202
|
+
|
|
2203
|
+
|
|
2204
|
+
def _remove_tree_at(parent_fd: int, name: str, *, missing_ok: bool = False) -> None:
|
|
2205
|
+
try:
|
|
2206
|
+
metadata = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
|
|
2207
|
+
except FileNotFoundError:
|
|
2208
|
+
if missing_ok:
|
|
2209
|
+
return
|
|
2210
|
+
raise
|
|
2211
|
+
if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISDIR(metadata.st_mode):
|
|
2212
|
+
raise APError(f"Install I/O refuses a symlink or non-directory tree: {name}")
|
|
2213
|
+
if not getattr(shutil.rmtree, "avoids_symlink_attacks", False):
|
|
2214
|
+
raise APError("This Python runtime cannot remove project trees without symlink attacks.")
|
|
2215
|
+
shutil.rmtree(name, dir_fd=parent_fd)
|
|
2216
|
+
|
|
2217
|
+
|
|
2218
|
+
def _copy_file_between_fds(
|
|
2219
|
+
source_parent_fd: int,
|
|
2220
|
+
source_name: str,
|
|
2221
|
+
destination_parent_fd: int,
|
|
2222
|
+
destination_name: str,
|
|
2223
|
+
) -> None:
|
|
2224
|
+
source_fd = -1
|
|
2225
|
+
destination_fd = -1
|
|
2226
|
+
temporary = f".{destination_name}.autocoding-{uuid.uuid4().hex}"
|
|
2227
|
+
try:
|
|
2228
|
+
source_fd = os.open(
|
|
2229
|
+
source_name,
|
|
2230
|
+
os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0),
|
|
2231
|
+
dir_fd=source_parent_fd,
|
|
2232
|
+
)
|
|
2233
|
+
source_metadata = os.fstat(source_fd)
|
|
2234
|
+
if not stat.S_ISREG(source_metadata.st_mode):
|
|
2235
|
+
raise APError(f"Install I/O source must be a regular file: {source_name}")
|
|
2236
|
+
destination_fd = os.open(
|
|
2237
|
+
temporary,
|
|
2238
|
+
os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
|
|
2239
|
+
stat.S_IMODE(source_metadata.st_mode),
|
|
2240
|
+
dir_fd=destination_parent_fd,
|
|
2241
|
+
)
|
|
2242
|
+
while True:
|
|
2243
|
+
block = os.read(source_fd, 1024 * 1024)
|
|
2244
|
+
if not block:
|
|
2245
|
+
break
|
|
2246
|
+
view = memoryview(block)
|
|
2247
|
+
while view:
|
|
2248
|
+
written = os.write(destination_fd, view)
|
|
2249
|
+
view = view[written:]
|
|
2250
|
+
os.fsync(destination_fd)
|
|
2251
|
+
os.close(destination_fd)
|
|
2252
|
+
destination_fd = -1
|
|
2253
|
+
os.replace(
|
|
2254
|
+
temporary,
|
|
2255
|
+
destination_name,
|
|
2256
|
+
src_dir_fd=destination_parent_fd,
|
|
2257
|
+
dst_dir_fd=destination_parent_fd,
|
|
2258
|
+
)
|
|
2259
|
+
except APError:
|
|
2260
|
+
raise
|
|
2261
|
+
except OSError as exc:
|
|
2262
|
+
raise APError(f"Cannot copy install transaction file safely: {destination_name}") from exc
|
|
2263
|
+
finally:
|
|
2264
|
+
if source_fd >= 0:
|
|
2265
|
+
os.close(source_fd)
|
|
2266
|
+
if destination_fd >= 0:
|
|
2267
|
+
os.close(destination_fd)
|
|
2268
|
+
with contextlib.suppress(OSError):
|
|
2269
|
+
os.unlink(temporary, dir_fd=destination_parent_fd)
|
|
2270
|
+
|
|
2271
|
+
|
|
2272
|
+
def _copy_directory_contents_fd(source_fd: int, destination_fd: int) -> None:
|
|
2273
|
+
for name in sorted(os.listdir(source_fd)):
|
|
2274
|
+
metadata = os.stat(name, dir_fd=source_fd, follow_symlinks=False)
|
|
2275
|
+
if stat.S_ISDIR(metadata.st_mode) and not stat.S_ISLNK(metadata.st_mode):
|
|
2276
|
+
os.mkdir(name, stat.S_IMODE(metadata.st_mode), dir_fd=destination_fd)
|
|
2277
|
+
source_child = _open_directory_at(source_fd, name)
|
|
2278
|
+
destination_child = _open_directory_at(destination_fd, name)
|
|
2279
|
+
try:
|
|
2280
|
+
_copy_directory_contents_fd(source_child, destination_child)
|
|
2281
|
+
finally:
|
|
2282
|
+
os.close(destination_child)
|
|
2283
|
+
os.close(source_child)
|
|
2284
|
+
elif stat.S_ISREG(metadata.st_mode):
|
|
2285
|
+
_copy_file_between_fds(source_fd, name, destination_fd, name)
|
|
2286
|
+
else:
|
|
2287
|
+
raise APError(f"Install I/O refuses a non-regular tree entry: {name}")
|
|
2288
|
+
|
|
2289
|
+
|
|
2290
|
+
def _copy_directory_at(
|
|
2291
|
+
source_parent_fd: int,
|
|
2292
|
+
source_name: str,
|
|
2293
|
+
destination_parent_fd: int,
|
|
2294
|
+
destination_name: str,
|
|
2295
|
+
) -> None:
|
|
2296
|
+
source_fd = _open_directory_at(source_parent_fd, source_name)
|
|
2297
|
+
destination_fd = -1
|
|
2298
|
+
try:
|
|
2299
|
+
source_metadata = os.fstat(source_fd)
|
|
2300
|
+
os.mkdir(destination_name, stat.S_IMODE(source_metadata.st_mode), dir_fd=destination_parent_fd)
|
|
2301
|
+
destination_fd = _open_directory_at(destination_parent_fd, destination_name)
|
|
2302
|
+
try:
|
|
2303
|
+
_copy_directory_contents_fd(source_fd, destination_fd)
|
|
2304
|
+
except BaseException:
|
|
2305
|
+
os.close(destination_fd)
|
|
2306
|
+
destination_fd = -1
|
|
2307
|
+
with contextlib.suppress(OSError, APError):
|
|
2308
|
+
_remove_tree_at(destination_parent_fd, destination_name, missing_ok=True)
|
|
2309
|
+
raise
|
|
2310
|
+
finally:
|
|
2311
|
+
if destination_fd >= 0:
|
|
2312
|
+
os.close(destination_fd)
|
|
2313
|
+
finally:
|
|
2314
|
+
os.close(source_fd)
|
|
2315
|
+
|
|
2316
|
+
|
|
2317
|
+
def _unlink_file_at(parent_fd: int, name: str, *, missing_ok: bool = False) -> None:
|
|
2318
|
+
try:
|
|
2319
|
+
metadata = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
|
|
2320
|
+
except FileNotFoundError:
|
|
2321
|
+
if missing_ok:
|
|
2322
|
+
return
|
|
2323
|
+
raise
|
|
2324
|
+
if stat.S_ISDIR(metadata.st_mode):
|
|
2325
|
+
raise APError(f"Install I/O refuses to unlink a directory as a file: {name}")
|
|
2326
|
+
os.unlink(name, dir_fd=parent_fd)
|
|
2327
|
+
|
|
2328
|
+
|
|
2329
|
+
def _install_io_owner(repo: Path) -> dict:
|
|
2330
|
+
payload = _safe_read_project_file(
|
|
2331
|
+
repo,
|
|
2332
|
+
_INSTALL_TRANSACTION_RELATIVE / "owner.json",
|
|
2333
|
+
max_bytes=4096,
|
|
2334
|
+
)
|
|
2335
|
+
if payload is None:
|
|
2336
|
+
raise APError("Install I/O requires a valid transaction owner.")
|
|
2337
|
+
try:
|
|
2338
|
+
owner = json.loads(payload.decode("utf-8"))
|
|
2339
|
+
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
|
|
2340
|
+
raise APError("Install I/O transaction owner is invalid.") from exc
|
|
2341
|
+
return _mapping(owner)
|
|
2342
|
+
|
|
2343
|
+
|
|
2344
|
+
def _require_install_io_access(repo: Path, operation: str) -> None:
|
|
2345
|
+
owner = _install_io_owner(repo)
|
|
2346
|
+
token = os.environ.get("AUTOCODING_INSTALL_TRANSACTION_TOKEN", "")
|
|
2347
|
+
expected = _text(owner.get("token_sha256"))
|
|
2348
|
+
if re.fullmatch(r"[0-9a-f]{64}", token) and re.fullmatch(r"[0-9a-f]{64}", expected):
|
|
2349
|
+
actual = hashlib.sha256(token.encode("ascii")).hexdigest()
|
|
2350
|
+
if hmac.compare_digest(actual, expected):
|
|
2351
|
+
return
|
|
2352
|
+
if operation in {"recover", "complete"}:
|
|
2353
|
+
try:
|
|
2354
|
+
pid = int(owner.get("pid"))
|
|
2355
|
+
os.kill(pid, 0)
|
|
2356
|
+
except ProcessLookupError:
|
|
2357
|
+
return
|
|
2358
|
+
except PermissionError as exc:
|
|
2359
|
+
raise APError("Install I/O recovery owner is still active.") from exc
|
|
2360
|
+
except (TypeError, ValueError, OSError) as exc:
|
|
2361
|
+
raise APError("Install I/O recovery owner cannot be verified.") from exc
|
|
2362
|
+
raise APError("Install I/O recovery owner is still active.")
|
|
2363
|
+
raise APError("Install I/O requires the active installer token.")
|
|
2364
|
+
|
|
2365
|
+
|
|
2366
|
+
def _cmd_install_io_posix(args: argparse.Namespace, repo: Path) -> None:
|
|
2367
|
+
operation = _text(args.operation).lower()
|
|
2368
|
+
if operation in {"switch", "recover"}:
|
|
2369
|
+
_safe_ensure_project_directory(repo, Path(".agents/skills"))
|
|
2370
|
+
if operation == "recover":
|
|
2371
|
+
_safe_ensure_project_directory(repo, Path("docs"))
|
|
2372
|
+
with contextlib.ExitStack() as stack:
|
|
2373
|
+
agents = stack.enter_context(_open_project_directory(repo, Path(".agents")))
|
|
2374
|
+
transaction = stack.enter_context(
|
|
2375
|
+
_open_project_directory(repo, _INSTALL_TRANSACTION_RELATIVE)
|
|
2376
|
+
)
|
|
2377
|
+
if not isinstance(agents, int) or not isinstance(transaction, int):
|
|
2378
|
+
raise APError("Install I/O project directories are missing.")
|
|
2379
|
+
bindings: list[tuple[Path, int, tuple[int, int]]] = [
|
|
2380
|
+
(Path(".agents"), agents, _directory_handle_identity(agents)),
|
|
2381
|
+
(_INSTALL_TRANSACTION_RELATIVE, transaction, _directory_handle_identity(transaction)),
|
|
2382
|
+
]
|
|
2383
|
+
skills: int | None = None
|
|
2384
|
+
docs: int | None = None
|
|
2385
|
+
if operation in {"switch", "recover"}:
|
|
2386
|
+
skills = stack.enter_context(_open_project_directory(repo, Path(".agents/skills")))
|
|
2387
|
+
if not isinstance(skills, int):
|
|
2388
|
+
raise APError("Install I/O skills directory is missing.")
|
|
2389
|
+
bindings.append((Path(".agents/skills"), skills, _directory_handle_identity(skills)))
|
|
2390
|
+
if operation == "recover":
|
|
2391
|
+
docs = stack.enter_context(_open_project_directory(repo, Path("docs")))
|
|
2392
|
+
if not isinstance(docs, int):
|
|
2393
|
+
raise APError("Install I/O docs directory is missing.")
|
|
2394
|
+
bindings.append((Path("docs"), docs, _directory_handle_identity(docs)))
|
|
2395
|
+
|
|
2396
|
+
_inject_install_io_parent_swap(repo, operation)
|
|
2397
|
+
for relative, handle, identity in bindings:
|
|
2398
|
+
_require_bound_project_directory(repo, relative, handle, identity)
|
|
2399
|
+
|
|
2400
|
+
if operation == "switch":
|
|
2401
|
+
assert skills is not None
|
|
2402
|
+
_remove_tree_at(skills, "auto-coding-skill", missing_ok=True)
|
|
2403
|
+
os.rename(
|
|
2404
|
+
"new-skill",
|
|
2405
|
+
"auto-coding-skill",
|
|
2406
|
+
src_dir_fd=transaction,
|
|
2407
|
+
dst_dir_fd=skills,
|
|
2408
|
+
)
|
|
2409
|
+
_copy_file_between_fds(transaction, "new-manifest.json", agents, "managed-install.json")
|
|
2410
|
+
elif operation == "recover":
|
|
2411
|
+
assert skills is not None and docs is not None
|
|
2412
|
+
_remove_tree_at(skills, "auto-coding-skill", missing_ok=True)
|
|
2413
|
+
if args.old_skill_present:
|
|
2414
|
+
_copy_directory_at(transaction, "old-skill", skills, "auto-coding-skill")
|
|
2415
|
+
if args.old_manifest_present:
|
|
2416
|
+
_copy_file_between_fds(transaction, "old-manifest.json", agents, "managed-install.json")
|
|
2417
|
+
else:
|
|
2418
|
+
_unlink_file_at(agents, "managed-install.json", missing_ok=True)
|
|
2419
|
+
if args.old_engineering_present:
|
|
2420
|
+
_copy_file_between_fds(transaction, "old-ENGINEERING.md", docs, "ENGINEERING.md")
|
|
2421
|
+
else:
|
|
2422
|
+
_unlink_file_at(docs, "ENGINEERING.md", missing_ok=True)
|
|
2423
|
+
elif operation == "complete":
|
|
2424
|
+
completed = f".auto-coding-skill-install-completed-{os.getpid()}-{uuid.uuid4().hex}"
|
|
2425
|
+
os.rename(
|
|
2426
|
+
_INSTALL_TRANSACTION_RELATIVE.name,
|
|
2427
|
+
completed,
|
|
2428
|
+
src_dir_fd=agents,
|
|
2429
|
+
dst_dir_fd=agents,
|
|
2430
|
+
)
|
|
2431
|
+
_remove_tree_at(agents, completed)
|
|
2432
|
+
else:
|
|
2433
|
+
raise APError(f"Unsupported install I/O operation: {operation}")
|
|
2434
|
+
|
|
2435
|
+
|
|
2436
|
+
def _cmd_install_io_windows(args: argparse.Namespace, repo: Path) -> None:
|
|
2437
|
+
operation = _text(args.operation).lower()
|
|
2438
|
+
if operation in {"switch", "recover"}:
|
|
2439
|
+
_safe_ensure_project_directory(repo, Path(".agents/skills"))
|
|
2440
|
+
if operation == "recover":
|
|
2441
|
+
_safe_ensure_project_directory(repo, Path("docs"))
|
|
2442
|
+
transaction = repo / _INSTALL_TRANSACTION_RELATIVE
|
|
2443
|
+
skills = repo / ".agents" / "skills"
|
|
2444
|
+
agents = repo / ".agents"
|
|
2445
|
+
docs = repo / "docs"
|
|
2446
|
+
snapshots: list[tuple[Path, tuple[int, int]]] = []
|
|
2447
|
+
for directory in [agents, transaction, *([skills] if operation in {"switch", "recover"} else []), *([docs] if operation == "recover" else [])]:
|
|
2448
|
+
metadata = directory.lstat()
|
|
2449
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISDIR(metadata.st_mode):
|
|
2450
|
+
raise APError(f"Install I/O project directory is unsafe: {directory.relative_to(repo)}")
|
|
2451
|
+
snapshots.append((directory, _project_path_identity(metadata)))
|
|
2452
|
+
_inject_install_io_parent_swap(repo, operation)
|
|
2453
|
+
|
|
2454
|
+
def validate() -> None:
|
|
2455
|
+
for directory, identity in snapshots:
|
|
2456
|
+
metadata = directory.lstat()
|
|
2457
|
+
if (
|
|
2458
|
+
_is_windows_reparse_point(metadata)
|
|
2459
|
+
or not stat.S_ISDIR(metadata.st_mode)
|
|
2460
|
+
or _project_path_identity(metadata) != identity
|
|
2461
|
+
):
|
|
2462
|
+
raise APError(f"Install I/O project parent changed: {directory.relative_to(repo)}")
|
|
2463
|
+
|
|
2464
|
+
validate()
|
|
2465
|
+
if operation == "switch":
|
|
2466
|
+
target = skills / "auto-coding-skill"
|
|
2467
|
+
if os.path.lexists(target):
|
|
2468
|
+
shutil.rmtree(target)
|
|
2469
|
+
os.replace(transaction / "new-skill", target)
|
|
2470
|
+
_safe_write_project_file(repo, Path(".agents/managed-install.json"), (transaction / "new-manifest.json").read_bytes())
|
|
2471
|
+
elif operation == "recover":
|
|
2472
|
+
target = skills / "auto-coding-skill"
|
|
2473
|
+
if os.path.lexists(target):
|
|
2474
|
+
shutil.rmtree(target)
|
|
2475
|
+
if args.old_skill_present:
|
|
2476
|
+
shutil.copytree(transaction / "old-skill", target, symlinks=True)
|
|
2477
|
+
if args.old_manifest_present:
|
|
2478
|
+
_safe_write_project_file(repo, Path(".agents/managed-install.json"), (transaction / "old-manifest.json").read_bytes())
|
|
2479
|
+
elif os.path.lexists(agents / "managed-install.json"):
|
|
2480
|
+
(agents / "managed-install.json").unlink()
|
|
2481
|
+
if args.old_engineering_present:
|
|
2482
|
+
_safe_write_project_file(repo, Path("docs/ENGINEERING.md"), (transaction / "old-ENGINEERING.md").read_bytes())
|
|
2483
|
+
elif os.path.lexists(docs / "ENGINEERING.md"):
|
|
2484
|
+
(docs / "ENGINEERING.md").unlink()
|
|
2485
|
+
elif operation == "complete":
|
|
2486
|
+
completed = agents / f".auto-coding-skill-install-completed-{os.getpid()}-{uuid.uuid4().hex}"
|
|
2487
|
+
os.replace(transaction, completed)
|
|
2488
|
+
shutil.rmtree(completed)
|
|
2489
|
+
else:
|
|
2490
|
+
raise APError(f"Unsupported install I/O operation: {operation}")
|
|
2491
|
+
validate()
|
|
2492
|
+
|
|
2493
|
+
|
|
2494
|
+
def cmd_install_io(args: argparse.Namespace) -> None:
|
|
2495
|
+
repo = Path(args.repo).resolve()
|
|
2496
|
+
operation = _text(args.operation).lower()
|
|
2497
|
+
_require_install_io_access(repo, operation)
|
|
2498
|
+
if os.name == "nt":
|
|
2499
|
+
_cmd_install_io_windows(args, repo)
|
|
2500
|
+
else:
|
|
2501
|
+
_cmd_install_io_posix(args, repo)
|
|
2502
|
+
if args.json:
|
|
2503
|
+
print(json.dumps({"operation": operation, "ok": True}))
|
|
2504
|
+
|
|
2505
|
+
|
|
2506
|
+
def _managed_scaffold_convergence(
|
|
2507
|
+
repo: Path,
|
|
2508
|
+
selected: dict[str, str],
|
|
2509
|
+
version: str,
|
|
2510
|
+
*,
|
|
2511
|
+
write: bool,
|
|
2512
|
+
) -> list[dict]:
|
|
2513
|
+
actions: list[dict] = []
|
|
2514
|
+
for rel, canonical in sorted(selected.items()):
|
|
2515
|
+
if rel not in MANAGED_FRAMEWORK_DOCS:
|
|
2516
|
+
continue
|
|
2517
|
+
current = _safe_read_project_file(repo, rel)
|
|
2518
|
+
expected = canonical.encode("utf-8")
|
|
2519
|
+
if current == expected:
|
|
2520
|
+
continue
|
|
2521
|
+
if current is not None:
|
|
2522
|
+
archive_rel, archive_required = _select_project_archive_target(
|
|
2523
|
+
repo,
|
|
2524
|
+
Path(".agents") / "archive" / "auto-coding-skill" / version / rel,
|
|
2525
|
+
current,
|
|
2526
|
+
legacy_digest_payload=current,
|
|
2527
|
+
)
|
|
2528
|
+
if archive_required:
|
|
2529
|
+
actions.append({"action": "archive", "path": archive_rel.as_posix()})
|
|
2530
|
+
if write:
|
|
2531
|
+
_safe_create_project_file(repo, archive_rel, current)
|
|
2532
|
+
actions.append({"action": "create" if current is None else "replace", "path": rel})
|
|
2533
|
+
if write:
|
|
2534
|
+
_safe_write_project_file(repo, rel, expected)
|
|
2535
|
+
return actions
|
|
2536
|
+
|
|
2537
|
+
|
|
2538
|
+
def _is_allowed_project_doc(rel: Path, candidate: Path | None = None) -> bool:
|
|
2539
|
+
if rel == _PROJECT_CONFIG_RELATIVE:
|
|
2540
|
+
return candidate is None or (candidate.is_file() and not candidate.is_symlink())
|
|
2541
|
+
if any(rel.match(pattern) for pattern in PROJECT_FEEDBACK_PATTERNS):
|
|
2542
|
+
return candidate is None or (candidate.is_file() and not candidate.is_symlink())
|
|
2543
|
+
return any(rel == root or root in rel.parents for root in _PROJECT_ARTIFACT_ROOTS)
|
|
2544
|
+
|
|
2545
|
+
|
|
2546
|
+
def cmd_project_converge(args: argparse.Namespace) -> None:
|
|
2547
|
+
repo = Path(args.repo).resolve()
|
|
2548
|
+
template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
|
|
2549
|
+
engineering = repo / "docs" / "ENGINEERING.md"
|
|
2550
|
+
config_plan = _project_config_convergence_plan(repo, template)
|
|
2551
|
+
output = config_plan["engineering_output"]
|
|
2552
|
+
current = config_plan["engineering_current"]
|
|
2553
|
+
changed = current != output
|
|
2554
|
+
actions: list[dict] = []
|
|
2555
|
+
version = _text(_mapping(_read_frontmatter_markdown(template)[0].get("workflow")).get("skill_version")) or "current"
|
|
2556
|
+
managed_templates = templates_for("all")
|
|
2557
|
+
managed_plan = _managed_scaffold_convergence(repo, managed_templates, version, write=False)
|
|
2558
|
+
|
|
2559
|
+
def archive_previous(source_path: Path, content: str, label: str) -> None:
|
|
2560
|
+
archive = (
|
|
2561
|
+
Path(".agents") / "archive" / "auto-coding-skill" / version
|
|
2562
|
+
/ source_path.relative_to(repo)
|
|
2563
|
+
)
|
|
2564
|
+
content_bytes = content.encode("utf-8")
|
|
2565
|
+
archive, archive_required = _select_project_archive_target(
|
|
2566
|
+
repo,
|
|
2567
|
+
archive,
|
|
2568
|
+
content_bytes,
|
|
2569
|
+
legacy_digest_payload=content_bytes,
|
|
2570
|
+
)
|
|
2571
|
+
if not archive_required:
|
|
2572
|
+
return
|
|
2573
|
+
actions.append({"action": "archive", "path": archive.as_posix(), "detail": label})
|
|
2574
|
+
if args.write:
|
|
2575
|
+
_safe_create_project_file(repo, archive, content_bytes)
|
|
2576
|
+
|
|
2577
|
+
def archive_extra(source_path: Path, label: str) -> None:
|
|
2578
|
+
source_rel = source_path.relative_to(repo)
|
|
2579
|
+
content = _safe_read_project_file(repo, source_rel)
|
|
2580
|
+
if content is None:
|
|
2581
|
+
raise APError(f"Project file disappeared during convergence: {source_rel.as_posix()}")
|
|
2582
|
+
archive, archive_required = _select_project_archive_target(
|
|
2583
|
+
repo,
|
|
2584
|
+
Path(".agents") / "archive" / "auto-coding-skill" / version / source_rel,
|
|
2585
|
+
content,
|
|
2586
|
+
legacy_digest_payload=content,
|
|
2587
|
+
)
|
|
2588
|
+
if archive_required:
|
|
2589
|
+
actions.append({"action": "archive", "path": archive.as_posix(), "detail": label})
|
|
2590
|
+
if args.write:
|
|
2591
|
+
_safe_create_project_file(repo, archive, content)
|
|
2592
|
+
|
|
2593
|
+
if changed and current:
|
|
2594
|
+
archive_header = (
|
|
2595
|
+
f"# Archived ENGINEERING.md before auto-coding-skill {version}\n\n"
|
|
2596
|
+
"Historical and non-authoritative. Do not use this file as workflow policy.\n\n---\n\n"
|
|
2597
|
+
)
|
|
2598
|
+
archive_previous(engineering, archive_header + current, "previous project configuration")
|
|
2599
|
+
if config_plan["overlay_output"] is not None:
|
|
2600
|
+
actions.append({
|
|
2601
|
+
"action": "create",
|
|
2602
|
+
"path": _PROJECT_CONFIG_RELATIVE.as_posix(),
|
|
2603
|
+
"detail": (
|
|
2604
|
+
"project-owned effective-config overlay; migrated "
|
|
2605
|
+
f"{len(config_plan['migrated_paths'])} value paths"
|
|
2606
|
+
),
|
|
2607
|
+
})
|
|
2608
|
+
if args.write:
|
|
2609
|
+
_safe_create_project_file(
|
|
2610
|
+
repo,
|
|
2611
|
+
_PROJECT_CONFIG_RELATIVE,
|
|
2612
|
+
config_plan["overlay_output"],
|
|
2613
|
+
)
|
|
2614
|
+
if changed:
|
|
2615
|
+
actions.append({
|
|
2616
|
+
"action": "create" if not current else "replace",
|
|
2617
|
+
"path": "docs/ENGINEERING.md",
|
|
2618
|
+
})
|
|
2619
|
+
if args.write:
|
|
2620
|
+
_safe_write_project_file(repo, Path("docs/ENGINEERING.md"), output.encode("utf-8"))
|
|
2621
|
+
|
|
2622
|
+
for rel, canonical in sorted(templates_for("all").items()):
|
|
2623
|
+
if rel in MANAGED_FRAMEWORK_DOCS:
|
|
2624
|
+
continue
|
|
2625
|
+
target = repo / rel
|
|
2626
|
+
existing_payload = _safe_read_project_file(repo, rel)
|
|
2627
|
+
try:
|
|
2628
|
+
existing = existing_payload.decode("utf-8") if existing_payload is not None else ""
|
|
2629
|
+
except UnicodeDecodeError as exc:
|
|
2630
|
+
raise APError(f"Project documentation must be UTF-8: {rel}") from exc
|
|
2631
|
+
managed = rel in MANAGED_FRAMEWORK_DOCS
|
|
2632
|
+
if existing and (not managed or existing == canonical):
|
|
2633
|
+
continue
|
|
2634
|
+
if existing:
|
|
2635
|
+
archive_previous(target, existing, "previous managed documentation template")
|
|
2636
|
+
actions.append({"action": "create" if not existing else "replace", "path": rel})
|
|
2637
|
+
if args.write:
|
|
2638
|
+
_safe_write_project_file(repo, rel, canonical.encode("utf-8"))
|
|
2639
|
+
|
|
2640
|
+
actions.extend(
|
|
2641
|
+
_managed_scaffold_convergence(repo, managed_templates, version, write=True)
|
|
2642
|
+
if args.write
|
|
2643
|
+
else managed_plan
|
|
2644
|
+
)
|
|
2645
|
+
|
|
2646
|
+
allowed_docs = {
|
|
2647
|
+
Path("docs/ENGINEERING.md"),
|
|
2648
|
+
Path("docs/tools/autopipeline/ap.py"),
|
|
2649
|
+
_PROJECT_CONFIG_RELATIVE,
|
|
2650
|
+
*(Path(rel) for rel in templates_for("all")),
|
|
2651
|
+
}
|
|
2652
|
+
docs_root = repo / "docs"
|
|
2653
|
+
if docs_root.exists():
|
|
2654
|
+
for candidate in sorted(docs_root.rglob("*")):
|
|
2655
|
+
try:
|
|
2656
|
+
candidate_metadata = candidate.lstat()
|
|
2657
|
+
except OSError as exc:
|
|
2658
|
+
raise APError("Cannot inspect active project documentation safely") from exc
|
|
2659
|
+
if stat.S_ISDIR(candidate_metadata.st_mode) and not _is_windows_reparse_point(candidate_metadata):
|
|
2660
|
+
continue
|
|
2661
|
+
rel = candidate.relative_to(repo)
|
|
2662
|
+
if _is_windows_reparse_point(candidate_metadata) or not stat.S_ISREG(candidate_metadata.st_mode):
|
|
2663
|
+
raise APError(
|
|
2664
|
+
"Active project documentation must contain only real directories and "
|
|
2665
|
+
f"regular non-symlink files: {rel.as_posix()}"
|
|
2666
|
+
)
|
|
2667
|
+
if rel in allowed_docs or _is_allowed_project_doc(rel, candidate):
|
|
2668
|
+
continue
|
|
2669
|
+
archive_extra(candidate, "removed from the exact docs framework")
|
|
2670
|
+
actions.append({"action": "delete", "path": rel.as_posix()})
|
|
2671
|
+
if args.write:
|
|
2672
|
+
candidate.unlink()
|
|
2673
|
+
if args.write:
|
|
2674
|
+
for directory in sorted(
|
|
2675
|
+
(item for item in docs_root.rglob("*") if item.is_dir()),
|
|
2676
|
+
key=lambda item: len(item.parts),
|
|
2677
|
+
reverse=True,
|
|
2678
|
+
):
|
|
2679
|
+
try:
|
|
2680
|
+
directory.rmdir()
|
|
2681
|
+
except OSError:
|
|
2682
|
+
pass
|
|
2683
|
+
|
|
2684
|
+
result = {"changed": bool(actions), "mode": "write" if args.write else "plan", "actions": actions}
|
|
2685
|
+
if args.json:
|
|
2686
|
+
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
2687
|
+
return
|
|
2688
|
+
for action in actions:
|
|
2689
|
+
print(f"[project-converge] {action['action']}: {action['path']}")
|
|
2690
|
+
if not actions:
|
|
2691
|
+
print("[project-converge] OK: already current")
|
|
2692
|
+
|
|
2693
|
+
|
|
2694
|
+
def cmd_scaffold(args: argparse.Namespace) -> None:
|
|
2695
|
+
repo = Path(args.repo).resolve()
|
|
2696
|
+
group = str(args.group or "").strip().lower()
|
|
2697
|
+
try:
|
|
2698
|
+
selected = templates_for(group)
|
|
2699
|
+
except KeyError as exc:
|
|
2700
|
+
choices = ", ".join(scaffold_groups() + ["all"])
|
|
2701
|
+
raise APError(f"Unknown scaffold group '{group}'. Choose one of: {choices}") from exc
|
|
2702
|
+
|
|
2703
|
+
write = bool(args.write)
|
|
2704
|
+
force = bool(args.force)
|
|
2705
|
+
actions: list[dict] = []
|
|
2706
|
+
for rel, content in sorted(selected.items()):
|
|
2707
|
+
current = _safe_read_project_file(repo, rel)
|
|
2708
|
+
if current is not None and not force:
|
|
2709
|
+
actions.append({"path": rel, "action": "exists"})
|
|
2710
|
+
continue
|
|
2711
|
+
action = "write" if write else "would-write"
|
|
2712
|
+
actions.append({"path": rel, "action": action})
|
|
2713
|
+
if write:
|
|
2714
|
+
_safe_write_project_file(repo, rel, content.encode("utf-8"))
|
|
2715
|
+
|
|
2716
|
+
result = {"group": group, "mode": "write" if write else "plan", "actions": actions}
|
|
2717
|
+
if args.json:
|
|
2718
|
+
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
2719
|
+
return
|
|
2720
|
+
for item in actions:
|
|
2721
|
+
print(f"[scaffold] {item['action']}: {item['path']}")
|
|
2722
|
+
if not write:
|
|
2723
|
+
print("[scaffold] plan only; re-run with --write to create missing files")
|
|
2724
|
+
|
|
2725
|
+
|
|
2726
|
+
def cmd_managed_scaffold_converge(args: argparse.Namespace) -> None:
|
|
2727
|
+
repo = Path(args.repo).resolve()
|
|
2728
|
+
group = str(args.group or "").strip().lower()
|
|
2729
|
+
selected = templates_for(group)
|
|
2730
|
+
write = bool(args.write)
|
|
2731
|
+
template = _skill_root() / "data" / "templates" / "ENGINEERING.md"
|
|
2732
|
+
version = _text(_mapping(_read_frontmatter_markdown(template)[0].get("workflow")).get("skill_version")) or "current"
|
|
2733
|
+
actions = _managed_scaffold_convergence(repo, selected, version, write=write)
|
|
2734
|
+
result = {"group": group, "mode": "write" if write else "plan", "actions": actions}
|
|
2735
|
+
if args.json:
|
|
2736
|
+
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
2737
|
+
return
|
|
2738
|
+
for item in actions:
|
|
2739
|
+
print(f"[managed-scaffold-converge] {item['action']}: {item['path']}")
|
|
2740
|
+
|
|
2741
|
+
|
|
2742
|
+
_CONFIG_STATUS_FIELDS: tuple[tuple[str, tuple[str, ...], bool, bool], ...] = (
|
|
2743
|
+
("workflow.skill_version", ("workflow", "skill_version"), False, True),
|
|
2744
|
+
("workflow.mode", ("workflow", "mode"), False, True),
|
|
2745
|
+
("workflow.profile", ("workflow", "profile"), False, True),
|
|
2746
|
+
("workflow.completion", ("workflow", "completion"), False, True),
|
|
2747
|
+
("project.name", ("project", "name"), False, True),
|
|
2748
|
+
("concurrency.isolation", ("concurrency", "isolation"), False, True),
|
|
2749
|
+
("concurrency.base_ref", ("concurrency", "base_ref"), False, True),
|
|
2750
|
+
("concurrency.target_branch", ("concurrency", "target_branch"), False, True),
|
|
2751
|
+
("concurrency.branch_prefix", ("concurrency", "branch_prefix"), False, True),
|
|
2752
|
+
("concurrency.worktree_root", ("concurrency", "worktree_root"), False, True),
|
|
2753
|
+
("concurrency.cleanup_merged", ("concurrency", "cleanup_merged"), False, True),
|
|
2754
|
+
("concurrency.delete_remote_branch", ("concurrency", "delete_remote_branch"), False, True),
|
|
2755
|
+
("concurrency.disposable_ignored", ("concurrency", "disposable_ignored"), True, False),
|
|
2756
|
+
("validation.on_unmapped", ("validation", "on_unmapped"), False, True),
|
|
2757
|
+
("validation.max_command_seconds", ("validation", "max_command_seconds"), False, True),
|
|
2758
|
+
("validation.max_total_seconds", ("validation", "max_total_seconds"), False, True),
|
|
2759
|
+
("validation.routes", ("validation", "routes"), True, False),
|
|
2760
|
+
("risk.rules", ("risk", "rules"), True, False),
|
|
2761
|
+
("docs.framework", ("docs", "framework"), False, True),
|
|
2762
|
+
("access.project.frontend.url", ("access", "project", "frontend", "url"), False, False),
|
|
2763
|
+
("access.project.frontend.username", ("access", "project", "frontend", "username"), False, False),
|
|
2764
|
+
("access.project.frontend.password", ("access", "project", "frontend", "password"), False, False),
|
|
2765
|
+
("access.project.backend.url", ("access", "project", "backend", "url"), False, False),
|
|
2766
|
+
("access.project.backend.username", ("access", "project", "backend", "username"), False, False),
|
|
2767
|
+
("access.project.backend.password", ("access", "project", "backend", "password"), False, False),
|
|
2768
|
+
("access.jenkins.frontend.url", ("access", "jenkins", "frontend", "url"), False, False),
|
|
2769
|
+
("access.jenkins.frontend.username", ("access", "jenkins", "frontend", "username"), False, False),
|
|
2770
|
+
("access.jenkins.frontend.password", ("access", "jenkins", "frontend", "password"), False, False),
|
|
2771
|
+
("access.jenkins.backend.url", ("access", "jenkins", "backend", "url"), False, False),
|
|
2772
|
+
("access.jenkins.backend.username", ("access", "jenkins", "backend", "username"), False, False),
|
|
2773
|
+
("access.jenkins.backend.password", ("access", "jenkins", "backend", "password"), False, False),
|
|
2774
|
+
("access.gitlab.url", ("access", "gitlab", "url"), False, False),
|
|
2775
|
+
("access.gitlab.username", ("access", "gitlab", "username"), False, False),
|
|
2776
|
+
("access.gitlab.password", ("access", "gitlab", "password"), False, False),
|
|
2777
|
+
("access.nexus.frontend.url", ("access", "nexus", "frontend", "url"), False, False),
|
|
2778
|
+
("access.nexus.frontend.username", ("access", "nexus", "frontend", "username"), False, False),
|
|
2779
|
+
("access.nexus.frontend.password", ("access", "nexus", "frontend", "password"), False, False),
|
|
2780
|
+
)
|
|
2781
|
+
|
|
2782
|
+
|
|
2783
|
+
def _config_value(cfg: dict, path: tuple[str, ...]) -> tuple[bool, object]:
|
|
2784
|
+
current: object = cfg
|
|
2785
|
+
for key in path:
|
|
2786
|
+
if not isinstance(current, dict) or key not in current:
|
|
2787
|
+
return False, ""
|
|
2788
|
+
current = current[key]
|
|
2789
|
+
return True, current
|
|
2790
|
+
|
|
2791
|
+
|
|
2792
|
+
def _config_status_report(repo: Path) -> dict:
|
|
2793
|
+
cfg = load_effective_config(repo)
|
|
2794
|
+
fields: dict[str, dict] = {}
|
|
2795
|
+
for label, path, sequence, expose_value in _CONFIG_STATUS_FIELDS:
|
|
2796
|
+
present, value = _config_value(cfg, path)
|
|
2797
|
+
if label.startswith("access.") or label in {"project.name", "docs.framework"}:
|
|
2798
|
+
configured = isinstance(value, str) and _is_explicit_fill(value)
|
|
2799
|
+
elif sequence:
|
|
2800
|
+
configured = isinstance(value, list) and bool(value)
|
|
2801
|
+
else:
|
|
2802
|
+
configured = bool(present and (
|
|
2803
|
+
len(value) > 0 if isinstance(value, (list, dict, str)) else value is not None
|
|
2804
|
+
))
|
|
2805
|
+
state = {
|
|
2806
|
+
"present": present,
|
|
2807
|
+
"configured": bool(present and configured),
|
|
2808
|
+
}
|
|
2809
|
+
if sequence:
|
|
2810
|
+
state["item_count"] = len(value) if isinstance(value, list) else -1
|
|
2811
|
+
if expose_value and present and isinstance(value, (str, bool, int, float)):
|
|
2812
|
+
state["value"] = value
|
|
2813
|
+
fields[label] = state
|
|
2814
|
+
commands = _mapping(cfg.get("commands"))
|
|
2815
|
+
overlay_payload = _safe_read_project_file(
|
|
2816
|
+
repo,
|
|
2817
|
+
_PROJECT_CONFIG_RELATIVE,
|
|
2818
|
+
max_bytes=128 * 1024,
|
|
2819
|
+
)
|
|
2820
|
+
contract = cmd_doctor(
|
|
2821
|
+
argparse.Namespace(repo=str(repo), collect=True, quiet=True, record=False)
|
|
2822
|
+
)
|
|
2823
|
+
report = {
|
|
2824
|
+
"schema": "auto-coding-skill/effective-config-status/v1",
|
|
2825
|
+
"managed_version": _text(_mapping(cfg.get("workflow")).get("skill_version")),
|
|
2826
|
+
"project_overlay": {
|
|
2827
|
+
"path": _PROJECT_CONFIG_RELATIVE.as_posix(),
|
|
2828
|
+
"present": overlay_payload is not None,
|
|
2829
|
+
"schema": PROJECT_CONFIG_SCHEMA if overlay_payload is not None else "",
|
|
2830
|
+
},
|
|
2831
|
+
"project": {"name": _text(_mapping(cfg.get("project")).get("name"))},
|
|
2832
|
+
"fields": fields,
|
|
2833
|
+
"commands": {
|
|
2834
|
+
"configured_names": sorted(
|
|
2835
|
+
str(name)
|
|
2836
|
+
for name, value in commands.items()
|
|
2837
|
+
if isinstance(name, str) and isinstance(value, str) and value.strip()
|
|
2838
|
+
)
|
|
2839
|
+
},
|
|
2840
|
+
"risk_rule_count": len(_mapping(cfg.get("risk")).get("rules") or [])
|
|
2841
|
+
if isinstance(_mapping(cfg.get("risk")).get("rules") or [], list)
|
|
2842
|
+
else -1,
|
|
2843
|
+
"validation_route_count": len(_mapping(cfg.get("validation")).get("routes") or [])
|
|
2844
|
+
if isinstance(_mapping(cfg.get("validation")).get("routes") or [], list)
|
|
2845
|
+
else -1,
|
|
2846
|
+
"policy_issues": _workflow_policy_issues(repo, cfg),
|
|
2847
|
+
"contract_valid": not bool(contract["issues"]),
|
|
2848
|
+
"contract_issues": contract["issues"],
|
|
2849
|
+
"contract_advisories": contract["advisories"],
|
|
2850
|
+
}
|
|
2851
|
+
canonical = json.dumps(report, ensure_ascii=True, sort_keys=True, separators=(",", ":"))
|
|
2852
|
+
report["redacted_sha256"] = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
|
|
2853
|
+
return report
|
|
2854
|
+
|
|
2855
|
+
|
|
2856
|
+
def cmd_config_effective(args: argparse.Namespace) -> None:
|
|
2857
|
+
report = _config_status_report(Path(args.repo).resolve())
|
|
2858
|
+
if args.json:
|
|
2859
|
+
print(json.dumps(report, ensure_ascii=False, indent=2))
|
|
2860
|
+
return
|
|
2861
|
+
print(f"[config] managed_version={report['managed_version'] or '(missing)'}")
|
|
2862
|
+
print(
|
|
2863
|
+
"[config] project_overlay="
|
|
2864
|
+
+ ("valid" if report["project_overlay"]["present"] else "missing")
|
|
2865
|
+
)
|
|
2866
|
+
print(f"[config] project={report['project']['name'] or '(missing)'}")
|
|
2867
|
+
print(f"[config] contract_valid={str(report['contract_valid']).lower()}")
|
|
2868
|
+
print(f"[config] redacted_sha256={report['redacted_sha256']}")
|
|
2869
|
+
|
|
2870
|
+
|
|
2871
|
+
def cmd_install(args: argparse.Namespace) -> None:
|
|
2872
|
+
repo = Path(args.repo).resolve()
|
|
2873
|
+
templates = _skill_root() / "data" / "templates"
|
|
2874
|
+
config_convergence = _project_config_convergence_plan(
|
|
2875
|
+
repo,
|
|
2876
|
+
templates / "ENGINEERING.md",
|
|
2877
|
+
)
|
|
2878
|
+
|
|
2879
|
+
planned_copies: list[tuple[Path, Path]] = []
|
|
2880
|
+
for rel in _CORE_DOC_TEMPLATES:
|
|
2881
|
+
planned_copies.append((templates / "docs" / rel, repo / "docs" / rel))
|
|
2882
|
+
|
|
2883
|
+
if args.bridges:
|
|
2884
|
+
planned_copies.append((templates / "bridges" / "AGENTS.md", repo / "AGENTS.md"))
|
|
2885
|
+
|
|
2886
|
+
tools_dir = repo / "docs" / "tools" / "autopipeline"
|
|
2887
|
+
planned_copies.append((templates / "tools" / "ap.py", tools_dir / "ap.py"))
|
|
2888
|
+
|
|
2889
|
+
engineering = repo / "docs" / "ENGINEERING.md"
|
|
2890
|
+
conflicts: list[Path] = [engineering] if config_convergence["engineering_current"] else []
|
|
2891
|
+
planned_files: list[tuple[Path, Path]] = []
|
|
2892
|
+
for src, dst in planned_copies:
|
|
2893
|
+
if src.is_file():
|
|
2894
|
+
planned_files.append((src, dst))
|
|
2895
|
+
continue
|
|
2896
|
+
for source_file in _iter_files(src):
|
|
2897
|
+
planned_files.append((source_file, dst / source_file.relative_to(src)))
|
|
2898
|
+
for _, dst in planned_files:
|
|
2899
|
+
if _safe_read_project_file(repo, dst.relative_to(repo)) is not None:
|
|
2900
|
+
conflicts.append(dst)
|
|
2901
|
+
if conflicts and not args.force:
|
|
2902
|
+
conflict_list = "\n".join(f"- {_repo_rel(repo, path)}" for path in conflicts[:20])
|
|
2903
|
+
extra = "" if len(conflicts) <= 20 else f"\n- ... and {len(conflicts) - 20} more"
|
|
2904
|
+
raise APError(
|
|
2905
|
+
"Install would overwrite existing files:\n"
|
|
2906
|
+
f"{conflict_list}{extra}\n"
|
|
2907
|
+
"For existing projects, run `autocoding init` or an explicit `autocoding sync`. "
|
|
2908
|
+
"Use `install --force` only when intentionally resetting generated docs/tooling."
|
|
2909
|
+
)
|
|
2910
|
+
|
|
2911
|
+
for src, dst in planned_files:
|
|
2912
|
+
_safe_write_project_file(repo, dst.relative_to(repo), src.read_bytes())
|
|
2913
|
+
|
|
2914
|
+
if config_convergence["overlay_output"] is not None:
|
|
2915
|
+
_safe_create_project_file(
|
|
2916
|
+
repo,
|
|
2917
|
+
_PROJECT_CONFIG_RELATIVE,
|
|
2918
|
+
config_convergence["overlay_output"],
|
|
2919
|
+
)
|
|
2920
|
+
_safe_write_project_file(
|
|
2921
|
+
repo,
|
|
2922
|
+
Path("docs/ENGINEERING.md"),
|
|
2923
|
+
config_convergence["engineering_output"].encode("utf-8"),
|
|
2924
|
+
)
|
|
2925
|
+
cmd_scaffold(
|
|
2926
|
+
argparse.Namespace(repo=str(repo), group="feedback", write=True, force=args.force, json=False)
|
|
2927
|
+
)
|
|
1398
2928
|
if args.full:
|
|
1399
2929
|
cmd_scaffold(
|
|
1400
2930
|
argparse.Namespace(repo=str(repo), group="all", write=True, force=args.force, json=False)
|
|
@@ -1404,7 +2934,7 @@ def cmd_install(args: argparse.Namespace) -> None:
|
|
|
1404
2934
|
print(f"[install] OK: {layout} scaffold installed into {repo}")
|
|
1405
2935
|
print(
|
|
1406
2936
|
"[install] Next: fill every access.* URL, username, and password in "
|
|
1407
|
-
"docs/
|
|
2937
|
+
"docs/project/auto-coding-skill.yaml, run doctor, and commit that file into Git."
|
|
1408
2938
|
)
|
|
1409
2939
|
|
|
1410
2940
|
|
|
@@ -1412,11 +2942,25 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
|
|
|
1412
2942
|
repo = Path(args.repo).resolve()
|
|
1413
2943
|
ensure_git_repo(repo)
|
|
1414
2944
|
write = bool(args.write) and not bool(args.dry_run)
|
|
2945
|
+
if write:
|
|
2946
|
+
raise APError(
|
|
2947
|
+
"Project-local `ap.py upgrade --write` was retired in favor of the "
|
|
2948
|
+
"transactional installer. Run `autocoding init` for one project or "
|
|
2949
|
+
"`autocoding sync --projects <path[,path...]>` for explicit projects. "
|
|
2950
|
+
"Use `ap.py upgrade --dry-run` only as a read-only legacy diagnostic."
|
|
2951
|
+
)
|
|
1415
2952
|
source_root = _find_skill_asset_root(repo)
|
|
1416
2953
|
templates = source_root / "data" / "templates"
|
|
1417
2954
|
template_engineering = templates / "ENGINEERING.md"
|
|
1418
2955
|
template_agents = templates / "bridges" / "AGENTS.md"
|
|
1419
2956
|
actions: list[dict] = []
|
|
2957
|
+
managed_version = _text(
|
|
2958
|
+
_mapping(_read_frontmatter_markdown(template_engineering)[0].get("workflow")).get("skill_version")
|
|
2959
|
+
) or "current"
|
|
2960
|
+
feedback_templates = templates_for("feedback")
|
|
2961
|
+
feedback_plan = _managed_scaffold_convergence(
|
|
2962
|
+
repo, feedback_templates, managed_version, write=False
|
|
2963
|
+
)
|
|
1420
2964
|
|
|
1421
2965
|
registry = _task_state_root(repo) / "tasks"
|
|
1422
2966
|
active_manifests = sorted(registry.glob("*.json")) if registry.exists() else []
|
|
@@ -1428,6 +2972,8 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
|
|
|
1428
2972
|
"workflow semantics must not change mid-task."
|
|
1429
2973
|
)
|
|
1430
2974
|
|
|
2975
|
+
config_convergence = _project_config_convergence_plan(repo, template_engineering)
|
|
2976
|
+
|
|
1431
2977
|
def add_action(kind: str, path: Path, action: str, detail: str = "") -> None:
|
|
1432
2978
|
actions.append({
|
|
1433
2979
|
"kind": kind,
|
|
@@ -1477,20 +3023,21 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
|
|
|
1477
3023
|
archive_header = (
|
|
1478
3024
|
f"# Archived ENGINEERING.md before auto-coding-skill {version} docs convergence\n\n"
|
|
1479
3025
|
"This file is historical and non-authoritative. Known duplicate workflow sections\n"
|
|
1480
|
-
"were removed from docs/ENGINEERING.md. Move
|
|
1481
|
-
"docs/
|
|
3026
|
+
"were removed from docs/ENGINEERING.md. Move still-current configuration into\n"
|
|
3027
|
+
"docs/project/auto-coding-skill.yaml and durable facts into docs/project/.\n\n---\n\n"
|
|
1482
3028
|
)
|
|
1483
3029
|
archive_content = archive_header + engineering_plan["original"]
|
|
1484
|
-
|
|
1485
|
-
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
|
-
|
|
1489
|
-
|
|
3030
|
+
archive_rel, archive_required = _select_project_archive_target(
|
|
3031
|
+
repo,
|
|
3032
|
+
Path("docs/archive/workflow") / f"ENGINEERING.pre-{version}.md",
|
|
3033
|
+
archive_content.encode("utf-8"),
|
|
3034
|
+
legacy_digest_payload=engineering_plan["original"].encode("utf-8"),
|
|
3035
|
+
)
|
|
3036
|
+
archive = repo / archive_rel
|
|
3037
|
+
if archive_required:
|
|
1490
3038
|
add_action("policy", archive, "archive", "before duplicate workflow section cleanup")
|
|
1491
3039
|
if write:
|
|
1492
|
-
|
|
1493
|
-
archive.write_text(archive_content, encoding="utf-8")
|
|
3040
|
+
_safe_create_project_file(repo, archive_rel, archive_content.encode("utf-8"))
|
|
1494
3041
|
|
|
1495
3042
|
tool_files = [
|
|
1496
3043
|
(
|
|
@@ -1543,23 +3090,24 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
|
|
|
1543
3090
|
current_agents = agents_path.read_text(encoding="utf-8") if agents_path.exists() else ""
|
|
1544
3091
|
if canonical_agents and current_agents != canonical_agents:
|
|
1545
3092
|
if current_agents:
|
|
1546
|
-
archive_dir = repo / "docs" / "archive" / "workflow"
|
|
1547
3093
|
archive_header = (
|
|
1548
|
-
"# Archived AGENTS.md before auto-coding-skill 4.
|
|
3094
|
+
"# Archived AGENTS.md before auto-coding-skill 4.3.1\n\n"
|
|
1549
3095
|
"This file is historical and non-authoritative. The root AGENTS.md is fully managed.\n"
|
|
1550
|
-
"Move
|
|
3096
|
+
"Move project configuration into docs/project/auto-coding-skill.yaml and facts into docs/project/,\n"
|
|
1551
3097
|
"without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
|
|
1552
3098
|
)
|
|
1553
3099
|
archive_content = archive_header + current_agents
|
|
1554
|
-
|
|
1555
|
-
|
|
1556
|
-
|
|
1557
|
-
|
|
1558
|
-
|
|
3100
|
+
archive_rel, archive_required = _select_project_archive_target(
|
|
3101
|
+
repo,
|
|
3102
|
+
Path("docs/archive/workflow/AGENTS.pre-4.3.1.md"),
|
|
3103
|
+
archive_content.encode("utf-8"),
|
|
3104
|
+
legacy_digest_payload=current_agents.encode("utf-8"),
|
|
3105
|
+
)
|
|
3106
|
+
archive = repo / archive_rel
|
|
3107
|
+
if archive_required:
|
|
1559
3108
|
add_action("policy", archive, "archive", "historical and non-authoritative")
|
|
1560
3109
|
if write:
|
|
1561
|
-
|
|
1562
|
-
archive.write_text(archive_content, encoding="utf-8")
|
|
3110
|
+
_safe_create_project_file(repo, archive_rel, archive_content.encode("utf-8"))
|
|
1563
3111
|
add_action("policy", agents_path, "replace", "fully managed canonical AGENTS.md")
|
|
1564
3112
|
if write:
|
|
1565
3113
|
agents_path.write_text(canonical_agents, encoding="utf-8")
|
|
@@ -1579,40 +3127,46 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
|
|
|
1579
3127
|
else:
|
|
1580
3128
|
add_action("doc", dst, "ok")
|
|
1581
3129
|
|
|
3130
|
+
feedback_actions = (
|
|
3131
|
+
_managed_scaffold_convergence(repo, feedback_templates, managed_version, write=True)
|
|
3132
|
+
if write
|
|
3133
|
+
else feedback_plan
|
|
3134
|
+
)
|
|
3135
|
+
for item in feedback_actions:
|
|
3136
|
+
actions.append({
|
|
3137
|
+
"kind": "doc",
|
|
3138
|
+
"path": item["path"],
|
|
3139
|
+
"action": item["action"],
|
|
3140
|
+
"detail": "managed Skill feedback template",
|
|
3141
|
+
})
|
|
3142
|
+
|
|
1582
3143
|
engineering = repo / "docs" / "ENGINEERING.md"
|
|
1583
|
-
if
|
|
1584
|
-
|
|
1585
|
-
|
|
1586
|
-
|
|
1587
|
-
|
|
3144
|
+
if config_convergence["overlay_output"] is not None:
|
|
3145
|
+
add_action(
|
|
3146
|
+
"config",
|
|
3147
|
+
repo / _PROJECT_CONFIG_RELATIVE,
|
|
3148
|
+
"create",
|
|
3149
|
+
f"migrate {len(config_convergence['migrated_paths'])} project-owned value paths",
|
|
3150
|
+
)
|
|
3151
|
+
if write:
|
|
3152
|
+
_safe_create_project_file(
|
|
3153
|
+
repo,
|
|
3154
|
+
_PROJECT_CONFIG_RELATIVE,
|
|
3155
|
+
config_convergence["overlay_output"],
|
|
3156
|
+
)
|
|
3157
|
+
engineering_output = config_convergence["engineering_output"]
|
|
3158
|
+
engineering_current = config_convergence["engineering_current"]
|
|
3159
|
+
if engineering_current != engineering_output:
|
|
3160
|
+
add_action(
|
|
3161
|
+
"config",
|
|
3162
|
+
engineering,
|
|
3163
|
+
"create" if not engineering_current else "replace",
|
|
3164
|
+
"managed default configuration",
|
|
1588
3165
|
)
|
|
1589
|
-
current_cfg, body = _parse_frontmatter_markdown_text(planned_engineering, engineering)
|
|
1590
|
-
template_cfg, _ = _read_frontmatter_markdown(template_engineering)
|
|
1591
|
-
merged_cfg = json.loads(json.dumps(current_cfg))
|
|
1592
|
-
added_keys = _deep_merge_missing(merged_cfg, template_cfg)
|
|
1593
|
-
migrated_keys = _migrate_fast_development_defaults(merged_cfg, repo)
|
|
1594
|
-
body_migrated = planned_engineering != engineering_plan["original"]
|
|
1595
|
-
if added_keys or migrated_keys or body_migrated:
|
|
1596
|
-
detail_parts = []
|
|
1597
|
-
if added_keys:
|
|
1598
|
-
detail_parts.append("add " + ", ".join(added_keys))
|
|
1599
|
-
if migrated_keys:
|
|
1600
|
-
detail_parts.append("migrate " + ", ".join(migrated_keys))
|
|
1601
|
-
if body_migrated:
|
|
1602
|
-
detail_parts.append(
|
|
1603
|
-
"remove known legacy workflow "
|
|
1604
|
-
+ ", ".join(item["id"] for item in engineering_plan["migrations"])
|
|
1605
|
-
)
|
|
1606
|
-
add_action("config", engineering, "merge", "; ".join(detail_parts))
|
|
1607
|
-
if write:
|
|
1608
|
-
_write_frontmatter_markdown(engineering, merged_cfg, body)
|
|
1609
|
-
else:
|
|
1610
|
-
add_action("config", engineering, "ok")
|
|
1611
|
-
elif template_engineering.exists():
|
|
1612
|
-
add_action("config", engineering, "create")
|
|
1613
3166
|
if write:
|
|
1614
|
-
|
|
1615
|
-
|
|
3167
|
+
_safe_write_project_file(repo, Path("docs/ENGINEERING.md"), engineering_output.encode("utf-8"))
|
|
3168
|
+
else:
|
|
3169
|
+
add_action("config", engineering, "ok")
|
|
1616
3170
|
|
|
1617
3171
|
result = {
|
|
1618
3172
|
"source_root": str(source_root),
|
|
@@ -1794,8 +3348,58 @@ def cmd_check_matrix(args: argparse.Namespace) -> None:
|
|
|
1794
3348
|
|
|
1795
3349
|
|
|
1796
3350
|
def _load_cfg(repo: Path) -> dict:
|
|
1797
|
-
|
|
1798
|
-
return
|
|
3351
|
+
_require_no_install_transaction(repo)
|
|
3352
|
+
return load_effective_config(repo)
|
|
3353
|
+
|
|
3354
|
+
|
|
3355
|
+
def _require_no_install_transaction(repo: Path, *, allow_installer: bool = False) -> None:
|
|
3356
|
+
transaction = repo / _INSTALL_TRANSACTION_RELATIVE
|
|
3357
|
+
if not os.path.lexists(transaction):
|
|
3358
|
+
return
|
|
3359
|
+
if allow_installer:
|
|
3360
|
+
_require_active_install_transaction(repo)
|
|
3361
|
+
return
|
|
3362
|
+
raise APError(
|
|
3363
|
+
"An interrupted auto-coding-skill install transaction requires recovery. "
|
|
3364
|
+
"Run autocoding init or a single-project autocoding sync before using or modifying the project runtime."
|
|
3365
|
+
)
|
|
3366
|
+
|
|
3367
|
+
|
|
3368
|
+
def _require_active_install_transaction(repo: Path) -> dict:
|
|
3369
|
+
transaction = repo / _INSTALL_TRANSACTION_RELATIVE
|
|
3370
|
+
if not os.path.lexists(transaction):
|
|
3371
|
+
raise APError("Internal project mutation requires an active install transaction.")
|
|
3372
|
+
token = os.environ.get("AUTOCODING_INSTALL_TRANSACTION_TOKEN", "")
|
|
3373
|
+
if not re.fullmatch(r"[0-9a-f]{64}", token):
|
|
3374
|
+
raise APError("Internal project mutation requires the active installer token.")
|
|
3375
|
+
owner_payload = _safe_read_project_file(
|
|
3376
|
+
repo,
|
|
3377
|
+
_INSTALL_TRANSACTION_RELATIVE / "owner.json",
|
|
3378
|
+
max_bytes=4096,
|
|
3379
|
+
)
|
|
3380
|
+
state_payload = _safe_read_project_file(
|
|
3381
|
+
repo,
|
|
3382
|
+
_INSTALL_TRANSACTION_RELATIVE / "state.json",
|
|
3383
|
+
max_bytes=64 * 1024,
|
|
3384
|
+
)
|
|
3385
|
+
if owner_payload is None or state_payload is None:
|
|
3386
|
+
raise APError("Internal project mutation requires a complete active install transaction.")
|
|
3387
|
+
try:
|
|
3388
|
+
owner = json.loads(owner_payload.decode("utf-8"))
|
|
3389
|
+
state = json.loads(state_payload.decode("utf-8"))
|
|
3390
|
+
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
|
|
3391
|
+
raise APError("Active install transaction metadata is invalid.") from exc
|
|
3392
|
+
actual = hashlib.sha256(token.encode("ascii")).hexdigest()
|
|
3393
|
+
owner_hash = _text(_mapping(owner).get("token_sha256"))
|
|
3394
|
+
state_owner_hash = _text(_mapping(state).get("owner_token_sha256"))
|
|
3395
|
+
internal_hash = _text(_mapping(state).get("internal_token_sha256"))
|
|
3396
|
+
if not all(
|
|
3397
|
+
re.fullmatch(r"[0-9a-f]{64}", value)
|
|
3398
|
+
and hmac.compare_digest(value, actual)
|
|
3399
|
+
for value in (owner_hash, state_owner_hash, internal_hash)
|
|
3400
|
+
):
|
|
3401
|
+
raise APError("Internal project mutation token does not match the active transaction.")
|
|
3402
|
+
return _mapping(state)
|
|
1799
3403
|
|
|
1800
3404
|
|
|
1801
3405
|
def _candidate_skill_roots(repo: Path) -> list[Path]:
|
|
@@ -2094,9 +3698,8 @@ def _workflow_document_plan(repo: Path, rel: str, policy: dict) -> dict:
|
|
|
2094
3698
|
if not match or (_text(rule.get("id")), line) in seen_issues:
|
|
2095
3699
|
continue
|
|
2096
3700
|
seen_issues.add((_text(rule.get("id")), line))
|
|
2097
|
-
snippet = " ".join(match.group(0).strip().split())[:180]
|
|
2098
3701
|
message = _text(rule.get("message")) or "conflicts with the fast development workflow"
|
|
2099
|
-
issues.append(f"{rel}:{line} [{_text(rule.get('id'))}] {message}
|
|
3702
|
+
issues.append(f"{rel}:{line} [{_text(rule.get('id'))}] {message}")
|
|
2100
3703
|
|
|
2101
3704
|
output = original
|
|
2102
3705
|
for start, end, _, _, replacement, match_mode in sorted(known, reverse=True):
|
|
@@ -2158,11 +3761,11 @@ def _legacy_gate_config_issues(cfg: dict) -> list[str]:
|
|
|
2158
3761
|
issues: list[str] = []
|
|
2159
3762
|
gate_cfg = cfg.get("gate") or {}
|
|
2160
3763
|
if not isinstance(gate_cfg, dict):
|
|
2161
|
-
return ["
|
|
3764
|
+
return ["effective configuration gate must be a mapping"]
|
|
2162
3765
|
if "full_on" in gate_cfg:
|
|
2163
|
-
issues.append("
|
|
3766
|
+
issues.append("effective configuration gate.full_on is legacy automatic full escalation; run autocoding init")
|
|
2164
3767
|
if _bool_config(gate_cfg.get("full_on_unknown"), False):
|
|
2165
|
-
issues.append("
|
|
3768
|
+
issues.append("effective configuration gate.full_on_unknown=true is legacy automatic full escalation; run autocoding init")
|
|
2166
3769
|
rules = gate_cfg.get("rules") or []
|
|
2167
3770
|
if isinstance(rules, list):
|
|
2168
3771
|
for index, rule in enumerate(rules):
|
|
@@ -2171,7 +3774,7 @@ def _legacy_gate_config_issues(cfg: dict) -> list[str]:
|
|
|
2171
3774
|
for key in ["scope", "commands"]:
|
|
2172
3775
|
if key in rule:
|
|
2173
3776
|
issues.append(
|
|
2174
|
-
f"
|
|
3777
|
+
f"effective configuration gate.rules[{index}].{key} is legacy automatic gate escalation; run autocoding init"
|
|
2175
3778
|
)
|
|
2176
3779
|
return issues
|
|
2177
3780
|
|
|
@@ -2183,7 +3786,7 @@ def _workflow_policy_issues(repo: Path, cfg: Optional[dict] = None) -> list[str]
|
|
|
2183
3786
|
for migration in plan["migrations"]:
|
|
2184
3787
|
issues.append(
|
|
2185
3788
|
f"{plan['path']}:{migration['line']} [{migration['id']}] known legacy workflow rule; "
|
|
2186
|
-
"run `
|
|
3789
|
+
"run `autocoding init` or an explicit `autocoding sync`"
|
|
2187
3790
|
)
|
|
2188
3791
|
issues.extend(_legacy_gate_config_issues(cfg if cfg is not None else _load_cfg(repo)))
|
|
2189
3792
|
return issues
|
|
@@ -2250,13 +3853,620 @@ def _text(value: object) -> str:
|
|
|
2250
3853
|
return str(value or "").strip()
|
|
2251
3854
|
|
|
2252
3855
|
|
|
3856
|
+
def _feedback_error(path: Path, message: str) -> APError:
|
|
3857
|
+
return APError(f"Invalid Skill feedback report {path}: {message}")
|
|
3858
|
+
|
|
3859
|
+
|
|
3860
|
+
def _feedback_scalar(data: dict, field: str, path: Path) -> str:
|
|
3861
|
+
value = data.get(field)
|
|
3862
|
+
if not isinstance(value, str) or not value.strip():
|
|
3863
|
+
raise _feedback_error(path, f"{field} must be a non-empty string")
|
|
3864
|
+
return value.strip()
|
|
3865
|
+
|
|
3866
|
+
|
|
3867
|
+
def _feedback_timestamp(value: object, path: Path, field: str) -> str:
|
|
3868
|
+
if isinstance(value, _dt.datetime):
|
|
3869
|
+
return value.isoformat()
|
|
3870
|
+
if isinstance(value, _dt.date):
|
|
3871
|
+
return value.isoformat()
|
|
3872
|
+
if not isinstance(value, str) or not value.strip():
|
|
3873
|
+
raise _feedback_error(path, f"{field} must be an ISO-8601 date or timestamp")
|
|
3874
|
+
raw = value.strip()
|
|
3875
|
+
try:
|
|
3876
|
+
if "T" in raw or " " in raw:
|
|
3877
|
+
_dt.datetime.fromisoformat(raw.replace("Z", "+00:00"))
|
|
3878
|
+
else:
|
|
3879
|
+
_dt.date.fromisoformat(raw)
|
|
3880
|
+
except ValueError as exc:
|
|
3881
|
+
raise _feedback_error(path, f"{field} must be an ISO-8601 date or timestamp") from exc
|
|
3882
|
+
return raw
|
|
3883
|
+
|
|
3884
|
+
|
|
3885
|
+
def _parse_feedback_report(payload: bytes, path: Path) -> dict:
|
|
3886
|
+
try:
|
|
3887
|
+
text = payload.decode("utf-8")
|
|
3888
|
+
except UnicodeDecodeError as exc:
|
|
3889
|
+
raise _feedback_error(path, "file must be UTF-8") from exc
|
|
3890
|
+
text = text.replace("\r\n", "\n").replace("\r", "\n")
|
|
3891
|
+
if "\x00" in text:
|
|
3892
|
+
raise _feedback_error(path, "file must be plain Markdown text")
|
|
3893
|
+
if any(pattern.search(text) for pattern in _FEEDBACK_SENSITIVE_PATTERNS):
|
|
3894
|
+
raise _feedback_error(path, "report contains sensitive or machine-specific evidence; redact it")
|
|
3895
|
+
match = re.match(r"^---[ \t]*\n(.*?)\n---[ \t]*(?:\n|$)(.*)$", text, flags=re.DOTALL)
|
|
3896
|
+
if not match:
|
|
3897
|
+
raise _feedback_error(path, "YAML frontmatter is required")
|
|
3898
|
+
try:
|
|
3899
|
+
data = require_yaml().safe_load(match.group(1))
|
|
3900
|
+
except Exception as exc:
|
|
3901
|
+
raise _feedback_error(path, "YAML frontmatter is not safe and valid") from exc
|
|
3902
|
+
if not isinstance(data, dict):
|
|
3903
|
+
raise _feedback_error(path, "YAML frontmatter must be a flat mapping")
|
|
3904
|
+
if any(not isinstance(key, str) for key in data):
|
|
3905
|
+
raise _feedback_error(path, "frontmatter field names must be strings")
|
|
3906
|
+
schema_value = _feedback_scalar(data, "schema", path)
|
|
3907
|
+
if schema_value not in _FEEDBACK_SCHEMAS:
|
|
3908
|
+
raise _feedback_error(path, "schema must be auto-coding-skill-feedback/v1 or /v2")
|
|
3909
|
+
expected_fields = _FEEDBACK_V2_FIELDS if schema_value.endswith("/v2") else _FEEDBACK_V1_FIELDS
|
|
3910
|
+
unknown = sorted(set(data) - set(expected_fields))
|
|
3911
|
+
missing = [field for field in expected_fields if field not in data]
|
|
3912
|
+
if unknown:
|
|
3913
|
+
raise _feedback_error(path, "unknown frontmatter fields are not allowed")
|
|
3914
|
+
if missing:
|
|
3915
|
+
raise _feedback_error(path, f"missing frontmatter fields: {', '.join(missing)}")
|
|
3916
|
+
if any(isinstance(value, (dict, list, tuple, set)) for value in data.values()):
|
|
3917
|
+
raise _feedback_error(path, "frontmatter values must be scalars")
|
|
3918
|
+
|
|
3919
|
+
metadata: dict[str, str] = {}
|
|
3920
|
+
metadata["schema"] = schema_value
|
|
3921
|
+
report_id = _feedback_scalar(data, "report_id", path)
|
|
3922
|
+
if not _FEEDBACK_SAFE_ID_RE.fullmatch(report_id):
|
|
3923
|
+
raise _feedback_error(path, "report_id must be a safe identifier")
|
|
3924
|
+
metadata["report_id"] = report_id
|
|
3925
|
+
status_value = _feedback_scalar(data, "status", path)
|
|
3926
|
+
if status_value not in _FEEDBACK_STATUSES:
|
|
3927
|
+
raise _feedback_error(path, "status is not supported")
|
|
3928
|
+
metadata["status"] = status_value
|
|
3929
|
+
metadata["created_at"] = _feedback_timestamp(data.get("created_at"), path, "created_at")
|
|
3930
|
+
metadata["updated_at"] = (
|
|
3931
|
+
_feedback_timestamp(data.get("updated_at"), path, "updated_at")
|
|
3932
|
+
if schema_value.endswith("/v2")
|
|
3933
|
+
else metadata["created_at"]
|
|
3934
|
+
)
|
|
3935
|
+
project_value = _feedback_scalar(data, "project", path)
|
|
3936
|
+
if not _FEEDBACK_SAFE_ID_RE.fullmatch(project_value):
|
|
3937
|
+
raise _feedback_error(path, "project must be a safe identifier")
|
|
3938
|
+
metadata["project"] = project_value
|
|
3939
|
+
version = _feedback_scalar(data, "observed_skill_version", path)
|
|
3940
|
+
if not _FEEDBACK_SEMVER_RE.fullmatch(version):
|
|
3941
|
+
raise _feedback_error(path, "observed_skill_version must be valid SemVer")
|
|
3942
|
+
metadata["observed_skill_version"] = version
|
|
3943
|
+
if schema_value.endswith("/v2"):
|
|
3944
|
+
last_verified = _feedback_scalar(data, "last_verified_skill_version", path)
|
|
3945
|
+
if not _FEEDBACK_SEMVER_RE.fullmatch(last_verified):
|
|
3946
|
+
raise _feedback_error(path, "last_verified_skill_version must be valid SemVer")
|
|
3947
|
+
else:
|
|
3948
|
+
last_verified = version
|
|
3949
|
+
metadata["last_verified_skill_version"] = last_verified
|
|
3950
|
+
component = _feedback_scalar(data, "component", path)
|
|
3951
|
+
if not _FEEDBACK_SLUG_RE.fullmatch(component):
|
|
3952
|
+
raise _feedback_error(path, "component must be a lowercase kebab-case slug")
|
|
3953
|
+
metadata["component"] = component
|
|
3954
|
+
kind = _feedback_scalar(data, "kind", path)
|
|
3955
|
+
if kind not in _FEEDBACK_KINDS:
|
|
3956
|
+
raise _feedback_error(path, "kind is not supported")
|
|
3957
|
+
metadata["kind"] = kind
|
|
3958
|
+
impact = _feedback_scalar(data, "impact", path)
|
|
3959
|
+
if impact not in _FEEDBACK_IMPACTS:
|
|
3960
|
+
raise _feedback_error(path, "impact is not supported")
|
|
3961
|
+
metadata["impact"] = impact
|
|
3962
|
+
origin_surface = _feedback_scalar(data, "origin_surface", path)
|
|
3963
|
+
if origin_surface not in _FEEDBACK_ORIGIN_SURFACES:
|
|
3964
|
+
raise _feedback_error(path, "origin_surface is not supported")
|
|
3965
|
+
metadata["origin_surface"] = origin_surface
|
|
3966
|
+
suspected_scope = _feedback_scalar(data, "suspected_scope", path)
|
|
3967
|
+
if suspected_scope != "shared":
|
|
3968
|
+
raise _feedback_error(path, "suspected_scope must be shared")
|
|
3969
|
+
metadata["suspected_scope"] = suspected_scope
|
|
3970
|
+
signature = _feedback_scalar(data, "signature", path)
|
|
3971
|
+
if not _FEEDBACK_SIGNATURE_RE.fullmatch(signature):
|
|
3972
|
+
raise _feedback_error(path, "signature must be sha256 followed by 64 lowercase hex characters")
|
|
3973
|
+
metadata["signature"] = signature
|
|
3974
|
+
if schema_value.endswith("/v2"):
|
|
3975
|
+
resolution = _feedback_scalar(data, "resolution", path)
|
|
3976
|
+
if resolution not in _FEEDBACK_RESOLUTIONS:
|
|
3977
|
+
raise _feedback_error(path, "resolution is not supported")
|
|
3978
|
+
if status_value in _FEEDBACK_ACTIVE_STATUSES and resolution != "pending":
|
|
3979
|
+
raise _feedback_error(path, "active status requires resolution=pending")
|
|
3980
|
+
if status_value == "resolved" and resolution != "fixed":
|
|
3981
|
+
raise _feedback_error(path, "status=resolved requires resolution=fixed")
|
|
3982
|
+
if status_value == "duplicate" and resolution != "duplicate":
|
|
3983
|
+
raise _feedback_error(path, "status=duplicate requires resolution=duplicate")
|
|
3984
|
+
if status_value == "rejected" and resolution not in {
|
|
3985
|
+
"project-config",
|
|
3986
|
+
"environment",
|
|
3987
|
+
"not-shared",
|
|
3988
|
+
"not-reproducible",
|
|
3989
|
+
"wont-fix",
|
|
3990
|
+
}:
|
|
3991
|
+
raise _feedback_error(path, "status=rejected requires a supported rejected resolution")
|
|
3992
|
+
elif status_value in _FEEDBACK_ACTIVE_STATUSES:
|
|
3993
|
+
resolution = "pending"
|
|
3994
|
+
elif status_value == "resolved":
|
|
3995
|
+
resolution = "fixed"
|
|
3996
|
+
elif status_value == "duplicate":
|
|
3997
|
+
resolution = "duplicate"
|
|
3998
|
+
else:
|
|
3999
|
+
resolution = "not-shared"
|
|
4000
|
+
metadata["resolution"] = resolution
|
|
4001
|
+
export_value = _feedback_scalar(data, "export", path)
|
|
4002
|
+
if export_value != "metadata-only":
|
|
4003
|
+
raise _feedback_error(path, "export must be metadata-only")
|
|
4004
|
+
metadata["export"] = export_value
|
|
4005
|
+
|
|
4006
|
+
body_lines = match.group(2).splitlines()
|
|
4007
|
+
titles = [line[2:].strip() for line in body_lines if line.startswith("# ")]
|
|
4008
|
+
if len(titles) != 1 or not titles[0]:
|
|
4009
|
+
raise _feedback_error(path, "body must contain exactly one non-empty level-one title")
|
|
4010
|
+
for heading in _FEEDBACK_HEADINGS:
|
|
4011
|
+
if body_lines.count(f"## {heading}") != 1:
|
|
4012
|
+
raise _feedback_error(path, f"body must contain exactly one '## {heading}' heading")
|
|
4013
|
+
heading_positions = [body_lines.index(f"## {heading}") for heading in _FEEDBACK_HEADINGS]
|
|
4014
|
+
if heading_positions != sorted(heading_positions):
|
|
4015
|
+
raise _feedback_error(path, "body headings must use the canonical order")
|
|
4016
|
+
for index, heading in enumerate(_FEEDBACK_HEADINGS):
|
|
4017
|
+
start = heading_positions[index] + 1
|
|
4018
|
+
end = heading_positions[index + 1] if index + 1 < len(heading_positions) else len(body_lines)
|
|
4019
|
+
if not any(line.strip() for line in body_lines[start:end]):
|
|
4020
|
+
raise _feedback_error(path, f"body section '{heading}' must not be empty")
|
|
4021
|
+
return metadata
|
|
4022
|
+
|
|
4023
|
+
|
|
4024
|
+
def _read_feedback_report(
|
|
4025
|
+
directory_fd: int | Path,
|
|
4026
|
+
name: str,
|
|
4027
|
+
display_path: Path,
|
|
4028
|
+
) -> tuple[bytes, int, tuple[int, int]]:
|
|
4029
|
+
flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
|
|
4030
|
+
descriptor = -1
|
|
4031
|
+
target = directory_fd / name if isinstance(directory_fd, Path) else None
|
|
4032
|
+
target_identity: tuple[int, int] | None = None
|
|
4033
|
+
try:
|
|
4034
|
+
if target is not None:
|
|
4035
|
+
checked = target.lstat()
|
|
4036
|
+
if _is_windows_reparse_point(checked) or not stat.S_ISREG(checked.st_mode):
|
|
4037
|
+
raise _feedback_error(display_path, "report must be a regular non-symlink file")
|
|
4038
|
+
target_identity = _project_path_identity(checked)
|
|
4039
|
+
descriptor = (
|
|
4040
|
+
os.open(target, flags)
|
|
4041
|
+
if isinstance(directory_fd, Path)
|
|
4042
|
+
else os.open(name, flags, dir_fd=directory_fd)
|
|
4043
|
+
)
|
|
4044
|
+
metadata = os.fstat(descriptor)
|
|
4045
|
+
if (
|
|
4046
|
+
not stat.S_ISREG(metadata.st_mode)
|
|
4047
|
+
or (target_identity is not None and _project_path_identity(metadata) != target_identity)
|
|
4048
|
+
):
|
|
4049
|
+
raise _feedback_error(display_path, "report must be a regular non-symlink file")
|
|
4050
|
+
if target is not None:
|
|
4051
|
+
checked = target.lstat()
|
|
4052
|
+
if (
|
|
4053
|
+
_is_windows_reparse_point(checked)
|
|
4054
|
+
or not stat.S_ISREG(checked.st_mode)
|
|
4055
|
+
or _project_path_identity(checked) != target_identity
|
|
4056
|
+
):
|
|
4057
|
+
raise _feedback_error(display_path, "report changed during its safety check")
|
|
4058
|
+
if metadata.st_size > _FEEDBACK_REPORT_MAX_BYTES:
|
|
4059
|
+
raise _feedback_error(display_path, f"report exceeds {_FEEDBACK_REPORT_MAX_BYTES} bytes")
|
|
4060
|
+
with os.fdopen(descriptor, "rb") as handle:
|
|
4061
|
+
descriptor = -1
|
|
4062
|
+
payload = handle.read(_FEEDBACK_REPORT_MAX_BYTES + 1)
|
|
4063
|
+
if target is not None:
|
|
4064
|
+
checked = target.lstat()
|
|
4065
|
+
if (
|
|
4066
|
+
_is_windows_reparse_point(checked)
|
|
4067
|
+
or not stat.S_ISREG(checked.st_mode)
|
|
4068
|
+
or _project_path_identity(checked) != target_identity
|
|
4069
|
+
):
|
|
4070
|
+
raise _feedback_error(display_path, "report changed while it was read")
|
|
4071
|
+
except APError:
|
|
4072
|
+
raise
|
|
4073
|
+
except OSError as exc:
|
|
4074
|
+
raise _feedback_error(display_path, "report could not be read safely") from exc
|
|
4075
|
+
finally:
|
|
4076
|
+
if descriptor >= 0:
|
|
4077
|
+
os.close(descriptor)
|
|
4078
|
+
if len(payload) > _FEEDBACK_REPORT_MAX_BYTES:
|
|
4079
|
+
raise _feedback_error(display_path, f"report exceeds {_FEEDBACK_REPORT_MAX_BYTES} bytes")
|
|
4080
|
+
return payload, len(payload), (int(metadata.st_dev), int(metadata.st_ino))
|
|
4081
|
+
|
|
4082
|
+
|
|
4083
|
+
def _feedback_project_root(raw: str) -> Path:
|
|
4084
|
+
try:
|
|
4085
|
+
root = Path(raw).expanduser().resolve(strict=True)
|
|
4086
|
+
except OSError as exc:
|
|
4087
|
+
raise APError(f"Skill feedback project does not exist: {raw}") from exc
|
|
4088
|
+
if not root.is_dir():
|
|
4089
|
+
raise APError(f"Skill feedback project is not a directory: {raw}")
|
|
4090
|
+
return root
|
|
4091
|
+
|
|
4092
|
+
|
|
4093
|
+
def _feedback_configured_project(root: Path) -> tuple[str, str]:
|
|
4094
|
+
config = load_effective_config(root)
|
|
4095
|
+
name = _text(_mapping(config.get("project")).get("name"))
|
|
4096
|
+
if not _FEEDBACK_SAFE_ID_RE.fullmatch(name):
|
|
4097
|
+
raise APError("Effective project.name must be a safe non-empty identifier for feedback")
|
|
4098
|
+
version = _text(_mapping(config.get("workflow")).get("skill_version"))
|
|
4099
|
+
if not _FEEDBACK_SEMVER_RE.fullmatch(version):
|
|
4100
|
+
raise APError("Effective workflow.skill_version must be valid SemVer for feedback")
|
|
4101
|
+
return name, version
|
|
4102
|
+
|
|
4103
|
+
|
|
4104
|
+
def _feedback_release_at_least(current: str, required: str) -> bool:
|
|
4105
|
+
def parts(value: str) -> tuple[tuple[int, int, int], bool]:
|
|
4106
|
+
match = re.fullmatch(r"([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([^+]+))?(?:\+.+)?", value)
|
|
4107
|
+
if not match:
|
|
4108
|
+
raise APError("Skill feedback version comparison requires valid SemVer")
|
|
4109
|
+
return tuple(int(match.group(index)) for index in range(1, 4)), bool(match.group(4))
|
|
4110
|
+
|
|
4111
|
+
current_core, current_prerelease = parts(current)
|
|
4112
|
+
required_core, required_prerelease = parts(required)
|
|
4113
|
+
if current_core != required_core:
|
|
4114
|
+
return current_core > required_core
|
|
4115
|
+
if current_prerelease != required_prerelease:
|
|
4116
|
+
return not current_prerelease
|
|
4117
|
+
return current == required or (not current_prerelease and not required_prerelease)
|
|
4118
|
+
|
|
4119
|
+
|
|
4120
|
+
def _load_feedback_resolution_catalog() -> dict[str, dict[str, str]]:
|
|
4121
|
+
path = _skill_root() / _FEEDBACK_RESOLUTION_POLICY
|
|
4122
|
+
try:
|
|
4123
|
+
metadata = path.lstat()
|
|
4124
|
+
except OSError as exc:
|
|
4125
|
+
raise APError("Managed Skill feedback resolution catalog is missing") from exc
|
|
4126
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
|
|
4127
|
+
raise APError("Managed Skill feedback resolution catalog must be a regular non-symlink file")
|
|
4128
|
+
if metadata.st_size > _FEEDBACK_RESOLUTION_MAX_BYTES:
|
|
4129
|
+
raise APError("Managed Skill feedback resolution catalog exceeds its size limit")
|
|
4130
|
+
try:
|
|
4131
|
+
payload = path.read_bytes()
|
|
4132
|
+
value = json.loads(payload)
|
|
4133
|
+
except (OSError, json.JSONDecodeError) as exc:
|
|
4134
|
+
raise APError("Managed Skill feedback resolution catalog is invalid") from exc
|
|
4135
|
+
if not isinstance(value, dict) or set(value) != {"schema", "entries"}:
|
|
4136
|
+
raise APError("Managed Skill feedback resolution catalog has an invalid top-level contract")
|
|
4137
|
+
if value.get("schema") != _FEEDBACK_RESOLUTION_SCHEMA or not isinstance(value.get("entries"), list):
|
|
4138
|
+
raise APError("Managed Skill feedback resolution catalog schema is invalid")
|
|
4139
|
+
catalog: dict[str, dict[str, str]] = {}
|
|
4140
|
+
ordered_signatures: list[str] = []
|
|
4141
|
+
for index, raw in enumerate(value["entries"]):
|
|
4142
|
+
if not isinstance(raw, dict):
|
|
4143
|
+
raise APError(f"Managed Skill feedback resolution entry {index} must be an object")
|
|
4144
|
+
allowed = {"signature", "disposition", "effective_skill_version", "canonical_signature"}
|
|
4145
|
+
if set(raw) - allowed or not {"signature", "disposition", "effective_skill_version"}.issubset(raw):
|
|
4146
|
+
raise APError(f"Managed Skill feedback resolution entry {index} has invalid fields")
|
|
4147
|
+
if any(not isinstance(item, str) or not item.strip() for item in raw.values()):
|
|
4148
|
+
raise APError(f"Managed Skill feedback resolution entry {index} values must be non-empty strings")
|
|
4149
|
+
signature = raw["signature"].strip()
|
|
4150
|
+
disposition = raw["disposition"].strip()
|
|
4151
|
+
effective = raw["effective_skill_version"].strip()
|
|
4152
|
+
if not _FEEDBACK_SIGNATURE_RE.fullmatch(signature):
|
|
4153
|
+
raise APError(f"Managed Skill feedback resolution entry {index} has an invalid signature")
|
|
4154
|
+
if disposition not in _FEEDBACK_CATALOG_DISPOSITIONS:
|
|
4155
|
+
raise APError(f"Managed Skill feedback resolution entry {index} has an invalid disposition")
|
|
4156
|
+
if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+", effective):
|
|
4157
|
+
raise APError(f"Managed Skill feedback resolution entry {index} has an invalid release version")
|
|
4158
|
+
canonical = _text(raw.get("canonical_signature"))
|
|
4159
|
+
if disposition == "duplicate":
|
|
4160
|
+
if not _FEEDBACK_SIGNATURE_RE.fullmatch(canonical) or canonical == signature:
|
|
4161
|
+
raise APError(f"Managed Skill feedback resolution entry {index} needs a distinct canonical signature")
|
|
4162
|
+
elif canonical:
|
|
4163
|
+
raise APError(f"Managed Skill feedback resolution entry {index} cannot set canonical_signature")
|
|
4164
|
+
if signature in catalog:
|
|
4165
|
+
raise APError("Managed Skill feedback resolution catalog contains duplicate signatures")
|
|
4166
|
+
entry = {
|
|
4167
|
+
"signature": signature,
|
|
4168
|
+
"disposition": disposition,
|
|
4169
|
+
"effective_skill_version": effective,
|
|
4170
|
+
}
|
|
4171
|
+
if canonical:
|
|
4172
|
+
entry["canonical_signature"] = canonical
|
|
4173
|
+
catalog[signature] = entry
|
|
4174
|
+
ordered_signatures.append(signature)
|
|
4175
|
+
if ordered_signatures != sorted(ordered_signatures):
|
|
4176
|
+
raise APError("Managed Skill feedback resolution entries must be sorted by signature")
|
|
4177
|
+
return catalog
|
|
4178
|
+
|
|
4179
|
+
|
|
4180
|
+
def _collect_project_feedback(
|
|
4181
|
+
root: Path,
|
|
4182
|
+
) -> tuple[list[dict], int, tuple[int, int] | None, set[tuple[int, int]], str, str]:
|
|
4183
|
+
reports_relative = Path("docs/skill-feedback/reports")
|
|
4184
|
+
configured_project, installed_skill_version = _feedback_configured_project(root)
|
|
4185
|
+
with _open_project_directory(root, reports_relative) as directory_fd:
|
|
4186
|
+
if directory_fd is None:
|
|
4187
|
+
return [], 0, None, set(), configured_project, installed_skill_version
|
|
4188
|
+
directory_metadata = (
|
|
4189
|
+
directory_fd.stat() if isinstance(directory_fd, Path) else os.fstat(directory_fd)
|
|
4190
|
+
)
|
|
4191
|
+
directory_identity = (int(directory_metadata.st_dev), int(directory_metadata.st_ino))
|
|
4192
|
+
try:
|
|
4193
|
+
entries = os.listdir(directory_fd)
|
|
4194
|
+
except OSError as exc:
|
|
4195
|
+
raise APError("Cannot list Skill feedback reports safely") from exc
|
|
4196
|
+
if len(entries) > _FEEDBACK_PROJECT_MAX_ENTRIES:
|
|
4197
|
+
raise APError(
|
|
4198
|
+
f"Skill feedback directory exceeds {_FEEDBACK_PROJECT_MAX_ENTRIES} entries"
|
|
4199
|
+
)
|
|
4200
|
+
candidates: list[str] = []
|
|
4201
|
+
for name in entries:
|
|
4202
|
+
if not name.endswith(".md"):
|
|
4203
|
+
continue
|
|
4204
|
+
if not _FEEDBACK_FILENAME_RE.fullmatch(name):
|
|
4205
|
+
raise APError("Skill feedback directory contains an invalid Markdown filename")
|
|
4206
|
+
try:
|
|
4207
|
+
metadata = (
|
|
4208
|
+
(directory_fd / name).stat(follow_symlinks=False)
|
|
4209
|
+
if isinstance(directory_fd, Path)
|
|
4210
|
+
else os.stat(name, dir_fd=directory_fd, follow_symlinks=False)
|
|
4211
|
+
)
|
|
4212
|
+
except OSError as exc:
|
|
4213
|
+
raise APError("Cannot inspect Skill feedback report safely") from exc
|
|
4214
|
+
if _is_windows_reparse_point(metadata) or not stat.S_ISREG(metadata.st_mode):
|
|
4215
|
+
raise APError(f"Skill feedback report must be a regular non-symlink file: {name}")
|
|
4216
|
+
candidates.append(name)
|
|
4217
|
+
candidates.sort()
|
|
4218
|
+
if len(candidates) > _FEEDBACK_PROJECT_MAX_REPORTS:
|
|
4219
|
+
raise APError(
|
|
4220
|
+
f"Skill feedback project exceeds {_FEEDBACK_PROJECT_MAX_REPORTS} reports"
|
|
4221
|
+
)
|
|
4222
|
+
|
|
4223
|
+
reports: list[dict] = []
|
|
4224
|
+
total_bytes = 0
|
|
4225
|
+
file_identities: set[tuple[int, int]] = set()
|
|
4226
|
+
for name in candidates:
|
|
4227
|
+
display_path = reports_relative / name
|
|
4228
|
+
payload, size, file_identity = _read_feedback_report(directory_fd, name, display_path)
|
|
4229
|
+
if file_identity in file_identities:
|
|
4230
|
+
raise APError("Skill feedback project contains duplicate physical report files")
|
|
4231
|
+
file_identities.add(file_identity)
|
|
4232
|
+
report = _parse_feedback_report(payload, display_path)
|
|
4233
|
+
if report["project"] != configured_project:
|
|
4234
|
+
raise _feedback_error(
|
|
4235
|
+
display_path,
|
|
4236
|
+
"project must equal effective project.name",
|
|
4237
|
+
)
|
|
4238
|
+
report["source_path"] = display_path.as_posix()
|
|
4239
|
+
report["size_bytes"] = size
|
|
4240
|
+
reports.append(report)
|
|
4241
|
+
total_bytes += size
|
|
4242
|
+
return (
|
|
4243
|
+
reports,
|
|
4244
|
+
total_bytes,
|
|
4245
|
+
directory_identity,
|
|
4246
|
+
file_identities,
|
|
4247
|
+
configured_project,
|
|
4248
|
+
installed_skill_version,
|
|
4249
|
+
)
|
|
4250
|
+
|
|
4251
|
+
|
|
4252
|
+
def _feedback_lifecycle(
|
|
4253
|
+
report: dict,
|
|
4254
|
+
installed_skill_version: str,
|
|
4255
|
+
catalog: dict[str, dict[str, str]],
|
|
4256
|
+
) -> tuple[str, str, dict[str, str] | None]:
|
|
4257
|
+
if report["status"] not in _FEEDBACK_ACTIVE_STATUSES:
|
|
4258
|
+
return "closed", "none", catalog.get(report["signature"])
|
|
4259
|
+
catalog_entry = catalog.get(report["signature"])
|
|
4260
|
+
if catalog_entry:
|
|
4261
|
+
effective = catalog_entry["effective_skill_version"]
|
|
4262
|
+
if not _feedback_release_at_least(installed_skill_version, effective):
|
|
4263
|
+
return "upgrade-due", "upgrade-project-then-verify", catalog_entry
|
|
4264
|
+
disposition = catalog_entry["disposition"]
|
|
4265
|
+
if disposition == "fixed":
|
|
4266
|
+
if report["last_verified_skill_version"] == installed_skill_version:
|
|
4267
|
+
return "regression-current", "none", catalog_entry
|
|
4268
|
+
if _feedback_release_at_least(report["last_verified_skill_version"], effective):
|
|
4269
|
+
return (
|
|
4270
|
+
"recheck-due",
|
|
4271
|
+
"reproduce-on-installed-version-and-update-or-close",
|
|
4272
|
+
catalog_entry,
|
|
4273
|
+
)
|
|
4274
|
+
return "verification-due", "verify-fix-then-resolve-or-delete", catalog_entry
|
|
4275
|
+
if disposition == "project-config":
|
|
4276
|
+
return (
|
|
4277
|
+
"reroute-due",
|
|
4278
|
+
"move-to-docs/project/auto-coding-skill.yaml-then-reject-or-delete",
|
|
4279
|
+
catalog_entry,
|
|
4280
|
+
)
|
|
4281
|
+
return "closure-due", "update-closed-status-or-delete", catalog_entry
|
|
4282
|
+
if report["last_verified_skill_version"] != installed_skill_version:
|
|
4283
|
+
return "recheck-due", "reproduce-on-installed-version-and-update-or-close", None
|
|
4284
|
+
return "active-current", "none", None
|
|
4285
|
+
|
|
4286
|
+
|
|
4287
|
+
def _feedback_groups(reports: list[dict]) -> list[dict]:
|
|
4288
|
+
grouped: dict[str, list[dict]] = {}
|
|
4289
|
+
for report in reports:
|
|
4290
|
+
grouped.setdefault(report["signature"], []).append(report)
|
|
4291
|
+
groups: list[dict] = []
|
|
4292
|
+
for signature, items in sorted(grouped.items()):
|
|
4293
|
+
projects = sorted({item["project"] for item in items})
|
|
4294
|
+
group_source_projects = sorted({item["source_project"] for item in items})
|
|
4295
|
+
groups.append(
|
|
4296
|
+
{
|
|
4297
|
+
"signature": signature,
|
|
4298
|
+
"report_count": len(items),
|
|
4299
|
+
"project_count": len(group_source_projects),
|
|
4300
|
+
"projects": projects,
|
|
4301
|
+
"source_projects": group_source_projects,
|
|
4302
|
+
"report_ids": [item["report_id"] for item in items],
|
|
4303
|
+
"cross_project": len(group_source_projects) > 1,
|
|
4304
|
+
}
|
|
4305
|
+
)
|
|
4306
|
+
return groups
|
|
4307
|
+
|
|
4308
|
+
|
|
4309
|
+
def _feedback_collection_result(raw_projects: list[str]) -> dict:
|
|
4310
|
+
if not raw_projects:
|
|
4311
|
+
raise APError("feedback-collect requires at least one explicit --project")
|
|
4312
|
+
catalog = _load_feedback_resolution_catalog()
|
|
4313
|
+
roots: list[Path] = []
|
|
4314
|
+
seen_roots: set[str] = set()
|
|
4315
|
+
for raw in raw_projects:
|
|
4316
|
+
root = _feedback_project_root(raw)
|
|
4317
|
+
key = str(root)
|
|
4318
|
+
if key not in seen_roots:
|
|
4319
|
+
seen_roots.add(key)
|
|
4320
|
+
roots.append(root)
|
|
4321
|
+
if len(roots) > _FEEDBACK_COLLECTION_MAX_PROJECTS:
|
|
4322
|
+
raise APError(
|
|
4323
|
+
f"Skill feedback collection exceeds {_FEEDBACK_COLLECTION_MAX_PROJECTS} projects"
|
|
4324
|
+
)
|
|
4325
|
+
|
|
4326
|
+
reports: list[dict] = []
|
|
4327
|
+
total_bytes = 0
|
|
4328
|
+
source_projects: list[dict[str, str]] = []
|
|
4329
|
+
seen_report_directories: set[tuple[int, int]] = set()
|
|
4330
|
+
seen_report_files: set[tuple[int, int]] = set()
|
|
4331
|
+
seen_configured_projects: set[str] = set()
|
|
4332
|
+
for index, root in enumerate(roots, start=1):
|
|
4333
|
+
source_id = f"project-{index}"
|
|
4334
|
+
(
|
|
4335
|
+
project_reports,
|
|
4336
|
+
project_bytes,
|
|
4337
|
+
directory_identity,
|
|
4338
|
+
file_identities,
|
|
4339
|
+
configured_project,
|
|
4340
|
+
installed_skill_version,
|
|
4341
|
+
) = _collect_project_feedback(root)
|
|
4342
|
+
if directory_identity is not None:
|
|
4343
|
+
if directory_identity in seen_report_directories:
|
|
4344
|
+
raise APError("Explicit projects resolve to the same Skill feedback report directory")
|
|
4345
|
+
seen_report_directories.add(directory_identity)
|
|
4346
|
+
if seen_report_files.intersection(file_identities):
|
|
4347
|
+
raise APError("Explicit projects contain the same physical Skill feedback report file")
|
|
4348
|
+
seen_report_files.update(file_identities)
|
|
4349
|
+
if configured_project in seen_configured_projects:
|
|
4350
|
+
raise APError("Explicit projects must have distinct effective project.name values")
|
|
4351
|
+
seen_configured_projects.add(configured_project)
|
|
4352
|
+
source_descriptor = {
|
|
4353
|
+
"source_project": source_id,
|
|
4354
|
+
"project": configured_project,
|
|
4355
|
+
"skill_version": installed_skill_version,
|
|
4356
|
+
}
|
|
4357
|
+
source_projects.append(source_descriptor)
|
|
4358
|
+
total_bytes += project_bytes
|
|
4359
|
+
if total_bytes > _FEEDBACK_COLLECTION_MAX_BYTES:
|
|
4360
|
+
raise APError(
|
|
4361
|
+
f"Skill feedback collection exceeds {_FEEDBACK_COLLECTION_MAX_BYTES} bytes"
|
|
4362
|
+
)
|
|
4363
|
+
if len(reports) + len(project_reports) > _FEEDBACK_COLLECTION_MAX_REPORTS:
|
|
4364
|
+
raise APError(
|
|
4365
|
+
f"Skill feedback collection exceeds {_FEEDBACK_COLLECTION_MAX_REPORTS} reports"
|
|
4366
|
+
)
|
|
4367
|
+
for report in project_reports:
|
|
4368
|
+
report["source_project"] = source_id
|
|
4369
|
+
report["installed_skill_version"] = installed_skill_version
|
|
4370
|
+
lifecycle, recommended_action, catalog_entry = _feedback_lifecycle(
|
|
4371
|
+
report,
|
|
4372
|
+
installed_skill_version,
|
|
4373
|
+
catalog,
|
|
4374
|
+
)
|
|
4375
|
+
report["lifecycle"] = lifecycle
|
|
4376
|
+
report["recommended_action"] = recommended_action
|
|
4377
|
+
if catalog_entry:
|
|
4378
|
+
report["catalog_disposition"] = catalog_entry["disposition"]
|
|
4379
|
+
report["catalog_effective_skill_version"] = catalog_entry["effective_skill_version"]
|
|
4380
|
+
if catalog_entry.get("canonical_signature"):
|
|
4381
|
+
report["catalog_canonical_signature"] = catalog_entry["canonical_signature"]
|
|
4382
|
+
reports.extend(project_reports)
|
|
4383
|
+
|
|
4384
|
+
reports.sort(key=lambda item: (item["signature"], item["project"], item["report_id"], item["source_path"]))
|
|
4385
|
+
triage_reports = [
|
|
4386
|
+
report
|
|
4387
|
+
for report in reports
|
|
4388
|
+
if report["lifecycle"] in {"active-current", "regression-current"}
|
|
4389
|
+
]
|
|
4390
|
+
groups = _feedback_groups(triage_reports)
|
|
4391
|
+
cross_project = [group for group in groups if group["cross_project"]]
|
|
4392
|
+
lifecycle_counts = {
|
|
4393
|
+
lifecycle: sum(1 for report in reports if report["lifecycle"] == lifecycle)
|
|
4394
|
+
for lifecycle in sorted({report["lifecycle"] for report in reports})
|
|
4395
|
+
}
|
|
4396
|
+
action_required = [
|
|
4397
|
+
{
|
|
4398
|
+
key: report[key]
|
|
4399
|
+
for key in (
|
|
4400
|
+
"source_project",
|
|
4401
|
+
"project",
|
|
4402
|
+
"report_id",
|
|
4403
|
+
"source_path",
|
|
4404
|
+
"signature",
|
|
4405
|
+
"installed_skill_version",
|
|
4406
|
+
"last_verified_skill_version",
|
|
4407
|
+
"lifecycle",
|
|
4408
|
+
"recommended_action",
|
|
4409
|
+
"catalog_disposition",
|
|
4410
|
+
"catalog_effective_skill_version",
|
|
4411
|
+
"catalog_canonical_signature",
|
|
4412
|
+
)
|
|
4413
|
+
if key in report
|
|
4414
|
+
}
|
|
4415
|
+
for report in reports
|
|
4416
|
+
if report["recommended_action"] != "none"
|
|
4417
|
+
]
|
|
4418
|
+
return {
|
|
4419
|
+
"schema": _FEEDBACK_COLLECTION_SCHEMA,
|
|
4420
|
+
"projects": source_projects,
|
|
4421
|
+
"report_count": len(reports),
|
|
4422
|
+
"active_report_count": len(triage_reports),
|
|
4423
|
+
"closed_report_count": lifecycle_counts.get("closed", 0),
|
|
4424
|
+
"action_required_count": len(action_required),
|
|
4425
|
+
"total_bytes": total_bytes,
|
|
4426
|
+
"lifecycle_counts": lifecycle_counts,
|
|
4427
|
+
"action_required": action_required,
|
|
4428
|
+
"metadata": reports,
|
|
4429
|
+
"groups": groups,
|
|
4430
|
+
"cross_project": cross_project,
|
|
4431
|
+
}
|
|
4432
|
+
|
|
4433
|
+
|
|
4434
|
+
def cmd_feedback_collect(args: argparse.Namespace) -> None:
|
|
4435
|
+
raw_projects = list(args.project or [])
|
|
4436
|
+
result = _feedback_collection_result(raw_projects)
|
|
4437
|
+
if args.json:
|
|
4438
|
+
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
4439
|
+
return
|
|
4440
|
+
print(
|
|
4441
|
+
f"[feedback-collect] projects={len(result['projects'])} reports={result['report_count']} "
|
|
4442
|
+
f"active={result['active_report_count']} closed={result['closed_report_count']} "
|
|
4443
|
+
f"actions={result['action_required_count']} groups={len(result['groups'])} "
|
|
4444
|
+
f"cross_project={len(result['cross_project'])} bytes={result['total_bytes']}"
|
|
4445
|
+
)
|
|
4446
|
+
for item in result["action_required"]:
|
|
4447
|
+
print(
|
|
4448
|
+
f"[feedback-collect] action={item['recommended_action']} "
|
|
4449
|
+
f"project={item['project']} report={item['report_id']} lifecycle={item['lifecycle']}"
|
|
4450
|
+
)
|
|
4451
|
+
for group in result["groups"]:
|
|
4452
|
+
print(
|
|
4453
|
+
f"[feedback-collect] signature={group['signature']} "
|
|
4454
|
+
f"cross_project={str(group['cross_project']).lower()} "
|
|
4455
|
+
f"projects={','.join(group['projects'])} reports={','.join(group['report_ids'])}"
|
|
4456
|
+
)
|
|
4457
|
+
|
|
4458
|
+
|
|
2253
4459
|
_TASK_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
|
|
2254
4460
|
_DIRECT_CLAIM_ID_RE = re.compile(r"^[0-9a-f]{32}$")
|
|
2255
4461
|
|
|
2256
4462
|
|
|
2257
4463
|
def _concurrency_cfg(cfg: dict) -> dict:
|
|
2258
|
-
value = cfg.get("concurrency")
|
|
2259
|
-
|
|
4464
|
+
value = cfg.get("concurrency")
|
|
4465
|
+
if value is None:
|
|
4466
|
+
return {}
|
|
4467
|
+
if not isinstance(value, dict):
|
|
4468
|
+
raise APError("concurrency must be a mapping")
|
|
4469
|
+
return value
|
|
2260
4470
|
|
|
2261
4471
|
|
|
2262
4472
|
def _task_isolation(cfg: dict) -> str:
|
|
@@ -3948,6 +6158,7 @@ _DEFAULT_FULL_PATH_PATTERNS = [
|
|
|
3948
6158
|
"compose*.yml",
|
|
3949
6159
|
"compose*.yaml",
|
|
3950
6160
|
"docs/ENGINEERING.md",
|
|
6161
|
+
_PROJECT_CONFIG_RELATIVE.as_posix(),
|
|
3951
6162
|
"docs/tools/autopipeline/**",
|
|
3952
6163
|
"package.json",
|
|
3953
6164
|
"**/package.json",
|
|
@@ -3967,18 +6178,30 @@ _DEFAULT_FULL_PATH_PATTERNS = [
|
|
|
3967
6178
|
|
|
3968
6179
|
|
|
3969
6180
|
def _gate_cfg(cfg: dict) -> dict:
|
|
3970
|
-
gate_cfg = cfg.get("gate")
|
|
3971
|
-
|
|
6181
|
+
gate_cfg = cfg.get("gate")
|
|
6182
|
+
if gate_cfg is None:
|
|
6183
|
+
return {}
|
|
6184
|
+
if not isinstance(gate_cfg, dict):
|
|
6185
|
+
raise APError("gate must be a mapping")
|
|
6186
|
+
return gate_cfg
|
|
3972
6187
|
|
|
3973
6188
|
|
|
3974
6189
|
def _risk_cfg(cfg: dict) -> dict:
|
|
3975
|
-
value = cfg.get("risk")
|
|
3976
|
-
|
|
6190
|
+
value = cfg.get("risk")
|
|
6191
|
+
if value is None:
|
|
6192
|
+
return {}
|
|
6193
|
+
if not isinstance(value, dict):
|
|
6194
|
+
raise APError("risk must be a mapping")
|
|
6195
|
+
return value
|
|
3977
6196
|
|
|
3978
6197
|
|
|
3979
6198
|
def _validation_cfg(cfg: dict) -> dict:
|
|
3980
|
-
value = cfg.get("validation")
|
|
3981
|
-
|
|
6199
|
+
value = cfg.get("validation")
|
|
6200
|
+
if value is None:
|
|
6201
|
+
return {}
|
|
6202
|
+
if not isinstance(value, dict):
|
|
6203
|
+
raise APError("validation must be a mapping")
|
|
6204
|
+
return value
|
|
3982
6205
|
|
|
3983
6206
|
|
|
3984
6207
|
def _positive_seconds(value: object, default: float, label: str) -> float:
|
|
@@ -4185,7 +6408,11 @@ def _cleanup_generated_noise(repo: Path, protected_paths: Optional[set[str]] = N
|
|
|
4185
6408
|
|
|
4186
6409
|
|
|
4187
6410
|
def _docs_only(paths: list[str]) -> bool:
|
|
4188
|
-
return bool(paths) and all(
|
|
6411
|
+
return bool(paths) and all(
|
|
6412
|
+
path not in _EFFECTIVE_CONFIG_PATHS
|
|
6413
|
+
and _path_matches(path, _DOC_PATH_PATTERNS)
|
|
6414
|
+
for path in paths
|
|
6415
|
+
)
|
|
4189
6416
|
|
|
4190
6417
|
|
|
4191
6418
|
def _tests_only(paths: list[str]) -> bool:
|
|
@@ -4199,13 +6426,46 @@ def _tests_only(paths: list[str]) -> bool:
|
|
|
4199
6426
|
|
|
4200
6427
|
|
|
4201
6428
|
def _gate_rules(gate_cfg: dict) -> list[dict]:
|
|
4202
|
-
rules = gate_cfg.get("rules"
|
|
4203
|
-
|
|
6429
|
+
rules = gate_cfg.get("rules", [])
|
|
6430
|
+
if not isinstance(rules, list):
|
|
6431
|
+
raise APError("gate.rules must be a list")
|
|
6432
|
+
validated: list[dict] = []
|
|
6433
|
+
for index, rule in enumerate(rules):
|
|
6434
|
+
if not isinstance(rule, dict):
|
|
6435
|
+
raise APError(f"gate.rules[{index}] must be a mapping")
|
|
6436
|
+
profile = _text(rule.get("profile")).lower()
|
|
6437
|
+
if profile and profile not in _WORKFLOW_PROFILES - {"auto"}:
|
|
6438
|
+
raise APError(
|
|
6439
|
+
f"gate.rules[{index}].profile must be micro, standard, or high-risk"
|
|
6440
|
+
)
|
|
6441
|
+
if "scope" in rule:
|
|
6442
|
+
raise APError(
|
|
6443
|
+
f"gate.rules[{index}].scope is legacy automatic gate escalation; run autocoding init"
|
|
6444
|
+
)
|
|
6445
|
+
if "commands" in rule:
|
|
6446
|
+
raise APError(
|
|
6447
|
+
f"gate.rules[{index}].commands is legacy automatic gate escalation; run autocoding init"
|
|
6448
|
+
)
|
|
6449
|
+
validated.append(rule)
|
|
6450
|
+
return validated
|
|
4204
6451
|
|
|
4205
6452
|
|
|
4206
6453
|
def _risk_rules(cfg: dict) -> list[dict]:
|
|
4207
|
-
rules = _risk_cfg(cfg).get("rules"
|
|
4208
|
-
|
|
6454
|
+
rules = _risk_cfg(cfg).get("rules", [])
|
|
6455
|
+
if not isinstance(rules, list):
|
|
6456
|
+
raise APError("risk.rules must be a list")
|
|
6457
|
+
current: list[dict] = []
|
|
6458
|
+
for index, rule in enumerate(rules):
|
|
6459
|
+
if not isinstance(rule, dict):
|
|
6460
|
+
raise APError(f"risk.rules[{index}] must be a mapping")
|
|
6461
|
+
if not _as_list(rule.get("paths")):
|
|
6462
|
+
raise APError(f"risk.rules[{index}].paths must not be empty")
|
|
6463
|
+
profile = _text(rule.get("profile")).lower()
|
|
6464
|
+
if profile and profile not in _WORKFLOW_PROFILES - {"auto"}:
|
|
6465
|
+
raise APError(
|
|
6466
|
+
f"risk.rules[{index}].profile must be micro, standard, or high-risk"
|
|
6467
|
+
)
|
|
6468
|
+
current.append(rule)
|
|
4209
6469
|
# Keep reading 3.x gate.rules while projects migrate. They remain planning
|
|
4210
6470
|
# metadata only and never execute validation commands.
|
|
4211
6471
|
return current or _gate_rules(_gate_cfg(cfg))
|
|
@@ -4230,8 +6490,19 @@ def _matching_risk_rules(paths: list[str], cfg: dict) -> list[dict]:
|
|
|
4230
6490
|
|
|
4231
6491
|
|
|
4232
6492
|
def _validation_routes(cfg: dict) -> list[dict]:
|
|
4233
|
-
routes = _validation_cfg(cfg).get("routes"
|
|
4234
|
-
|
|
6493
|
+
routes = _validation_cfg(cfg).get("routes", [])
|
|
6494
|
+
if not isinstance(routes, list):
|
|
6495
|
+
raise APError("validation.routes must be a list")
|
|
6496
|
+
validated: list[dict] = []
|
|
6497
|
+
for index, route in enumerate(routes):
|
|
6498
|
+
if not isinstance(route, dict):
|
|
6499
|
+
raise APError(f"validation.routes[{index}] must be a mapping")
|
|
6500
|
+
if not _as_list(route.get("paths")):
|
|
6501
|
+
raise APError(f"validation.routes[{index}].paths must not be empty")
|
|
6502
|
+
if not [_command_name(item) for item in _as_list(route.get("commands"))]:
|
|
6503
|
+
raise APError(f"validation.routes[{index}].commands must not be empty")
|
|
6504
|
+
validated.append(route)
|
|
6505
|
+
return validated
|
|
4235
6506
|
|
|
4236
6507
|
|
|
4237
6508
|
def _validation_route_matches(path: str, route: dict) -> bool:
|
|
@@ -4253,11 +6524,19 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
|
|
|
4253
6524
|
command_names: list[str] = []
|
|
4254
6525
|
command_timeouts: dict[str, float] = {}
|
|
4255
6526
|
matched_routes: list[str] = []
|
|
6527
|
+
builtins: list[str] = []
|
|
4256
6528
|
coverage: dict[str, list[str]] = {}
|
|
4257
6529
|
unmapped: list[str] = []
|
|
4258
6530
|
|
|
4259
6531
|
for path in normalized:
|
|
4260
6532
|
names: list[str] = []
|
|
6533
|
+
if path in _EFFECTIVE_CONFIG_PATHS:
|
|
6534
|
+
builtin_name = "effective-config"
|
|
6535
|
+
names.append(builtin_name)
|
|
6536
|
+
if builtin_name not in builtins:
|
|
6537
|
+
builtins.append(builtin_name)
|
|
6538
|
+
if builtin_name not in matched_routes:
|
|
6539
|
+
matched_routes.append(builtin_name)
|
|
4261
6540
|
for index, route in enumerate(routes):
|
|
4262
6541
|
if not _validation_route_matches(path, route):
|
|
4263
6542
|
continue
|
|
@@ -4289,7 +6568,13 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
|
|
|
4289
6568
|
|
|
4290
6569
|
validation_cfg = _validation_cfg(cfg)
|
|
4291
6570
|
compatibility_command = ""
|
|
4292
|
-
|
|
6571
|
+
project_validation_paths = [
|
|
6572
|
+
path
|
|
6573
|
+
for path in normalized
|
|
6574
|
+
if path not in _EFFECTIVE_CONFIG_PATHS
|
|
6575
|
+
and not _path_matches(path, _DOC_PATH_PATTERNS)
|
|
6576
|
+
]
|
|
6577
|
+
if not routes and project_validation_paths:
|
|
4293
6578
|
compatibility_command = _command_name(validation_cfg.get("fallback_command"))
|
|
4294
6579
|
if not compatibility_command and _configured_command(cfg, "gate_changed"):
|
|
4295
6580
|
compatibility_command = "gate_changed"
|
|
@@ -4313,6 +6598,7 @@ def _validation_plan(cfg: dict, paths: list[str]) -> dict:
|
|
|
4313
6598
|
"commands": command_names,
|
|
4314
6599
|
"command_timeouts": command_timeouts,
|
|
4315
6600
|
"matched_routes": matched_routes,
|
|
6601
|
+
"builtins": builtins,
|
|
4316
6602
|
"coverage": coverage,
|
|
4317
6603
|
"unmapped": unmapped,
|
|
4318
6604
|
"docs_only": _docs_only(normalized),
|
|
@@ -4328,9 +6614,9 @@ def _validate_validation_plan(cfg: dict, plan: dict) -> None:
|
|
|
4328
6614
|
raise APError(
|
|
4329
6615
|
"Changed code paths have no validation route:\n- "
|
|
4330
6616
|
+ "\n- ".join(plan["unmapped"])
|
|
4331
|
-
+ "\nAdd validation.routes entries in docs/
|
|
6617
|
+
+ "\nAdd validation.routes entries in docs/project/auto-coding-skill.yaml."
|
|
4332
6618
|
)
|
|
4333
|
-
if plan["paths"] and not plan["docs_only"] and not plan["commands"]:
|
|
6619
|
+
if plan["paths"] and not plan["docs_only"] and not plan["commands"] and not plan["builtins"]:
|
|
4334
6620
|
raise APError(
|
|
4335
6621
|
"Changed code has no fast validation command. Add validation.routes with project-native commands."
|
|
4336
6622
|
)
|
|
@@ -4448,6 +6734,14 @@ def _run_changed_gate(
|
|
|
4448
6734
|
deadline: Optional[float] = None,
|
|
4449
6735
|
command_timeout_s: Optional[float] = None,
|
|
4450
6736
|
) -> list[str]:
|
|
6737
|
+
contract = cmd_doctor(
|
|
6738
|
+
argparse.Namespace(repo=str(repo), collect=True, quiet=True, record=False)
|
|
6739
|
+
)
|
|
6740
|
+
if contract["issues"]:
|
|
6741
|
+
raise APError(
|
|
6742
|
+
"Effective project configuration contract is invalid:\n- "
|
|
6743
|
+
+ "\n- ".join(contract["issues"])
|
|
6744
|
+
)
|
|
4451
6745
|
plan = _validation_plan(cfg, paths)
|
|
4452
6746
|
_validate_validation_plan(cfg, plan)
|
|
4453
6747
|
if not paths:
|
|
@@ -4461,14 +6755,17 @@ def _run_changed_gate(
|
|
|
4461
6755
|
"[validation] WARN: using 3.x compatibility fallback; migrate to validation.routes",
|
|
4462
6756
|
file=sys.stderr,
|
|
4463
6757
|
)
|
|
4464
|
-
executed =
|
|
6758
|
+
executed = list(plan["builtins"])
|
|
6759
|
+
if plan["builtins"]:
|
|
6760
|
+
print("[validation] effective project configuration contract is valid")
|
|
6761
|
+
executed.extend(_run_configured_command_list(
|
|
4465
6762
|
repo,
|
|
4466
6763
|
cfg,
|
|
4467
6764
|
plan["commands"],
|
|
4468
6765
|
deadline=deadline,
|
|
4469
6766
|
command_timeout_s=command_timeout_s,
|
|
4470
6767
|
command_timeouts=plan["command_timeouts"],
|
|
4471
|
-
)
|
|
6768
|
+
))
|
|
4472
6769
|
print(
|
|
4473
6770
|
"[validation] routes="
|
|
4474
6771
|
+ (", ".join(plan["matched_routes"]) or "(none)")
|
|
@@ -4495,6 +6792,7 @@ def cmd_validation_map_check(args: argparse.Namespace) -> None:
|
|
|
4495
6792
|
"commands": plan["commands"],
|
|
4496
6793
|
"command_timeouts": plan["command_timeouts"],
|
|
4497
6794
|
"matched_routes": plan["matched_routes"],
|
|
6795
|
+
"builtins": plan["builtins"],
|
|
4498
6796
|
"coverage": plan["coverage"],
|
|
4499
6797
|
"docs_only": plan["docs_only"],
|
|
4500
6798
|
}
|
|
@@ -4711,18 +7009,30 @@ _DEFAULT_LAYER_RULES = {
|
|
|
4711
7009
|
|
|
4712
7010
|
|
|
4713
7011
|
def _structure_cfg(cfg: dict) -> dict:
|
|
4714
|
-
value = cfg.get("structure")
|
|
4715
|
-
|
|
7012
|
+
value = cfg.get("structure")
|
|
7013
|
+
if value is None:
|
|
7014
|
+
return {}
|
|
7015
|
+
if not isinstance(value, dict):
|
|
7016
|
+
raise APError("structure must be a mapping")
|
|
7017
|
+
return value
|
|
4716
7018
|
|
|
4717
7019
|
|
|
4718
7020
|
def _optimization_cfg(cfg: dict) -> dict:
|
|
4719
|
-
value = cfg.get("optimization")
|
|
4720
|
-
|
|
7021
|
+
value = cfg.get("optimization")
|
|
7022
|
+
if value is None:
|
|
7023
|
+
return {}
|
|
7024
|
+
if not isinstance(value, dict):
|
|
7025
|
+
raise APError("optimization must be a mapping")
|
|
7026
|
+
return value
|
|
4721
7027
|
|
|
4722
7028
|
|
|
4723
7029
|
def _verification_cfg(cfg: dict) -> dict:
|
|
4724
|
-
value = cfg.get("verification")
|
|
4725
|
-
|
|
7030
|
+
value = cfg.get("verification")
|
|
7031
|
+
if value is None:
|
|
7032
|
+
return {}
|
|
7033
|
+
if not isinstance(value, dict):
|
|
7034
|
+
raise APError("verification must be a mapping")
|
|
7035
|
+
return value
|
|
4726
7036
|
|
|
4727
7037
|
|
|
4728
7038
|
def _bool_config(value: object, default: bool = False) -> bool:
|
|
@@ -6582,14 +8892,24 @@ def _render_optimization_backlog(inventory: dict) -> str:
|
|
|
6582
8892
|
def _update_accepted_debt_paths(repo: Path, cfg: dict, paths: list[str]) -> list[str]:
|
|
6583
8893
|
if not paths:
|
|
6584
8894
|
return []
|
|
6585
|
-
|
|
6586
|
-
|
|
6587
|
-
|
|
6588
|
-
|
|
8895
|
+
overrides = json.loads(json.dumps(load_project_overrides(repo)))
|
|
8896
|
+
effective_structure = _mapping(cfg.get("structure"))
|
|
8897
|
+
existing = [
|
|
8898
|
+
str(item)
|
|
8899
|
+
for item in _as_list(effective_structure.get("accepted_debt_paths"))
|
|
8900
|
+
if str(item).strip()
|
|
8901
|
+
]
|
|
6589
8902
|
added = [path for path in paths if path not in existing]
|
|
6590
8903
|
if added:
|
|
8904
|
+
structure_cfg = overrides.setdefault("structure", {})
|
|
8905
|
+
if not isinstance(structure_cfg, dict):
|
|
8906
|
+
raise APError("Project structure override must be a mapping")
|
|
6591
8907
|
structure_cfg["accepted_debt_paths"] = existing + added
|
|
6592
|
-
|
|
8908
|
+
overlay_payload = _render_project_overlay(overrides)
|
|
8909
|
+
if _safe_read_project_file(repo, _PROJECT_CONFIG_RELATIVE) is None:
|
|
8910
|
+
_safe_create_project_file(repo, _PROJECT_CONFIG_RELATIVE, overlay_payload)
|
|
8911
|
+
else:
|
|
8912
|
+
_safe_write_project_file(repo, _PROJECT_CONFIG_RELATIVE, overlay_payload)
|
|
6593
8913
|
return added
|
|
6594
8914
|
|
|
6595
8915
|
|
|
@@ -6624,7 +8944,7 @@ def cmd_baseline_init(args: argparse.Namespace) -> None:
|
|
|
6624
8944
|
accepted_added = _update_accepted_debt_paths(repo, cfg, accepted_paths)
|
|
6625
8945
|
if accepted_added:
|
|
6626
8946
|
actions.append({
|
|
6627
|
-
"path":
|
|
8947
|
+
"path": _PROJECT_CONFIG_RELATIVE.as_posix(),
|
|
6628
8948
|
"action": "merge",
|
|
6629
8949
|
"kind": "accepted_debt_paths",
|
|
6630
8950
|
"detail": ", ".join(accepted_added),
|
|
@@ -8627,7 +10947,7 @@ def cmd_agent_result_template(args: argparse.Namespace) -> None:
|
|
|
8627
10947
|
def cmd_run(args: argparse.Namespace) -> None:
|
|
8628
10948
|
"""
|
|
8629
10949
|
Run any configured gate command by name.
|
|
8630
|
-
Commands are read from
|
|
10950
|
+
Commands are read from the effective managed-default plus project-overlay configuration.
|
|
8631
10951
|
"""
|
|
8632
10952
|
repo = Path(args.repo).resolve()
|
|
8633
10953
|
cfg = _load_cfg(repo)
|
|
@@ -8636,12 +10956,12 @@ def cmd_run(args: argparse.Namespace) -> None:
|
|
|
8636
10956
|
if name not in commands:
|
|
8637
10957
|
raise APError(
|
|
8638
10958
|
f"Command not configured: commands.{name}. "
|
|
8639
|
-
"Edit docs/
|
|
10959
|
+
"Edit docs/project/auto-coding-skill.yaml. "
|
|
8640
10960
|
f"Available: {', '.join(commands.keys()) or '(none)'}"
|
|
8641
10961
|
)
|
|
8642
10962
|
cmd = str(commands.get(name) or "").strip()
|
|
8643
10963
|
if not cmd:
|
|
8644
|
-
raise APError(f"Command is blank: commands.{name}. Edit docs/
|
|
10964
|
+
raise APError(f"Command is blank: commands.{name}. Edit docs/project/auto-coding-skill.yaml.")
|
|
8645
10965
|
print(f"[run] {name}: {cmd}")
|
|
8646
10966
|
run_shell(cmd, cwd=repo)
|
|
8647
10967
|
print(f"[run] OK: {name}")
|
|
@@ -8961,9 +11281,12 @@ def cmd_verify_jenkins(args: argparse.Namespace) -> None:
|
|
|
8961
11281
|
print(f"[verify-jenkins] OK: {jenkinsfile}")
|
|
8962
11282
|
|
|
8963
11283
|
|
|
8964
|
-
def cmd_doctor(args: argparse.Namespace) -> None:
|
|
11284
|
+
def cmd_doctor(args: argparse.Namespace) -> dict | None:
|
|
8965
11285
|
repo = Path(args.repo).resolve()
|
|
8966
11286
|
cfg = _load_cfg(repo)
|
|
11287
|
+
collect = bool(getattr(args, "collect", False))
|
|
11288
|
+
quiet = bool(getattr(args, "quiet", False))
|
|
11289
|
+
record = bool(getattr(args, "record", True))
|
|
8967
11290
|
workflow_cfg = (cfg.get("workflow") or {})
|
|
8968
11291
|
project_cfg = (cfg.get("project") or {})
|
|
8969
11292
|
docs_cfg = (cfg.get("docs") or {})
|
|
@@ -8976,9 +11299,18 @@ def cmd_doctor(args: argparse.Namespace) -> None:
|
|
|
8976
11299
|
advisories: List[str] = []
|
|
8977
11300
|
validation_errors.extend(_workflow_policy_issues(repo, cfg))
|
|
8978
11301
|
|
|
8979
|
-
|
|
8980
|
-
|
|
8981
|
-
|
|
11302
|
+
raw_mode = workflow_cfg.get("mode", "dev")
|
|
11303
|
+
raw_profile = workflow_cfg.get("profile", "auto")
|
|
11304
|
+
raw_completion = workflow_cfg.get("completion", "")
|
|
11305
|
+
if not isinstance(raw_mode, str):
|
|
11306
|
+
validation_errors.append("workflow.mode must be a string")
|
|
11307
|
+
if not isinstance(raw_profile, str):
|
|
11308
|
+
validation_errors.append("workflow.profile must be a string")
|
|
11309
|
+
if not isinstance(raw_completion, str):
|
|
11310
|
+
validation_errors.append("workflow.completion must be a string")
|
|
11311
|
+
mode = raw_mode.strip().lower() if isinstance(raw_mode, str) else ""
|
|
11312
|
+
profile = raw_profile.strip().lower() if isinstance(raw_profile, str) else ""
|
|
11313
|
+
completion = raw_completion.strip().lower() if isinstance(raw_completion, str) else ""
|
|
8982
11314
|
skill_version = _text(workflow_cfg.get("skill_version"))
|
|
8983
11315
|
if mode != "dev":
|
|
8984
11316
|
missing.append("workflow.mode (must be dev; external verification is owner-managed)")
|
|
@@ -8988,24 +11320,42 @@ def cmd_doctor(args: argparse.Namespace) -> None:
|
|
|
8988
11320
|
missing.append("workflow.completion (must be push)")
|
|
8989
11321
|
if skill_version.startswith("4.1") and _text(docs_cfg.get("framework")) != "engineering-centered":
|
|
8990
11322
|
missing.append("docs.framework (must be engineering-centered for auto-coding-skill 4.1)")
|
|
8991
|
-
|
|
8992
|
-
if
|
|
11323
|
+
raw_isolation = concurrency_cfg.get("isolation", "adaptive")
|
|
11324
|
+
if not isinstance(raw_isolation, str):
|
|
11325
|
+
validation_errors.append("concurrency.isolation must be a string")
|
|
11326
|
+
isolation = ""
|
|
11327
|
+
else:
|
|
11328
|
+
isolation = raw_isolation.strip().lower() or "adaptive"
|
|
11329
|
+
if isolation and isolation not in {"adaptive", "worktree"}:
|
|
8993
11330
|
validation_errors.append(
|
|
8994
11331
|
"concurrency.isolation must be adaptive or worktree; legacy shared-checkout mode is unsupported"
|
|
8995
11332
|
)
|
|
8996
|
-
|
|
8997
|
-
if not
|
|
11333
|
+
raw_branch_prefix = concurrency_cfg.get("branch_prefix", "codex/")
|
|
11334
|
+
if not isinstance(raw_branch_prefix, str):
|
|
11335
|
+
validation_errors.append("concurrency.branch_prefix must be a string")
|
|
11336
|
+
branch_prefix = ""
|
|
11337
|
+
else:
|
|
11338
|
+
branch_prefix = raw_branch_prefix.strip() or "codex/"
|
|
11339
|
+
if branch_prefix and not branch_prefix.endswith("/"):
|
|
8998
11340
|
validation_errors.append("concurrency.branch_prefix must end with '/'")
|
|
8999
|
-
elif run(
|
|
11341
|
+
elif branch_prefix and run(
|
|
9000
11342
|
["git", "check-ref-format", "--branch", f"{branch_prefix}TASK"],
|
|
9001
11343
|
cwd=repo,
|
|
9002
11344
|
check=False,
|
|
9003
11345
|
).returncode != 0:
|
|
9004
11346
|
validation_errors.append("concurrency.branch_prefix does not form a valid Git branch")
|
|
9005
|
-
|
|
11347
|
+
raw_project_name = project_cfg.get("name")
|
|
11348
|
+
if raw_project_name is not None and not isinstance(raw_project_name, str):
|
|
11349
|
+
validation_errors.append("project.name must be a string")
|
|
11350
|
+
if not isinstance(raw_project_name, str) or not raw_project_name.strip():
|
|
9006
11351
|
missing.append("project.name")
|
|
9007
11352
|
missing.extend(_access_config_issues(cfg))
|
|
9008
|
-
|
|
11353
|
+
raw_enforcement = structure_cfg.get("enforcement")
|
|
11354
|
+
if raw_enforcement is not None and not isinstance(raw_enforcement, str):
|
|
11355
|
+
validation_errors.append("structure.enforcement must be a string")
|
|
11356
|
+
enforcement = ""
|
|
11357
|
+
else:
|
|
11358
|
+
enforcement = raw_enforcement.strip().lower() if isinstance(raw_enforcement, str) else ""
|
|
9009
11359
|
if enforcement and enforcement not in {"advisory", "blocking"}:
|
|
9010
11360
|
validation_errors.append("structure.enforcement must be advisory or blocking")
|
|
9011
11361
|
raw_block_warnings = structure_cfg.get("block_warnings")
|
|
@@ -9017,7 +11367,7 @@ def cmd_doctor(args: argparse.Namespace) -> None:
|
|
|
9017
11367
|
)
|
|
9018
11368
|
gate_cfg = _gate_cfg(cfg)
|
|
9019
11369
|
if "full_on" in gate_cfg:
|
|
9020
|
-
validation_errors.append("gate.full_on is legacy automatic full escalation; run
|
|
11370
|
+
validation_errors.append("gate.full_on is legacy automatic full escalation; run autocoding init")
|
|
9021
11371
|
raw_rules = gate_cfg.get("rules") or []
|
|
9022
11372
|
rules_valid = isinstance(raw_rules, list)
|
|
9023
11373
|
if not rules_valid:
|
|
@@ -9038,12 +11388,12 @@ def cmd_doctor(args: argparse.Namespace) -> None:
|
|
|
9038
11388
|
if "scope" in rule:
|
|
9039
11389
|
rules_valid = False
|
|
9040
11390
|
validation_errors.append(
|
|
9041
|
-
f"gate.rules[{index}].scope is legacy automatic gate escalation; run
|
|
11391
|
+
f"gate.rules[{index}].scope is legacy automatic gate escalation; run autocoding init"
|
|
9042
11392
|
)
|
|
9043
11393
|
if "commands" in rule:
|
|
9044
11394
|
rules_valid = False
|
|
9045
11395
|
validation_errors.append(
|
|
9046
|
-
f"gate.rules[{index}].commands is legacy automatic gate escalation; run
|
|
11396
|
+
f"gate.rules[{index}].commands is legacy automatic gate escalation; run autocoding init"
|
|
9047
11397
|
)
|
|
9048
11398
|
|
|
9049
11399
|
risk_rules = _risk_cfg(cfg).get("rules") or []
|
|
@@ -9063,8 +11413,13 @@ def cmd_doctor(args: argparse.Namespace) -> None:
|
|
|
9063
11413
|
)
|
|
9064
11414
|
|
|
9065
11415
|
validation_cfg = _validation_cfg(cfg)
|
|
9066
|
-
|
|
9067
|
-
if
|
|
11416
|
+
raw_on_unmapped = validation_cfg.get("on_unmapped", "error")
|
|
11417
|
+
if not isinstance(raw_on_unmapped, str):
|
|
11418
|
+
validation_errors.append("validation.on_unmapped must be a string")
|
|
11419
|
+
on_unmapped = ""
|
|
11420
|
+
else:
|
|
11421
|
+
on_unmapped = raw_on_unmapped.strip().lower() or "error"
|
|
11422
|
+
if on_unmapped and on_unmapped not in {"error", "fallback"}:
|
|
9068
11423
|
validation_errors.append("validation.on_unmapped must be error or fallback")
|
|
9069
11424
|
try:
|
|
9070
11425
|
final_budget = _final_gate_budget(cfg)
|
|
@@ -9185,22 +11540,51 @@ def cmd_doctor(args: argparse.Namespace) -> None:
|
|
|
9185
11540
|
f"install integrity: {issue}" for issue in integrity["errors"]
|
|
9186
11541
|
)
|
|
9187
11542
|
|
|
11543
|
+
if (
|
|
11544
|
+
isinstance(raw_project_name, str)
|
|
11545
|
+
and _FEEDBACK_SAFE_ID_RE.fullmatch(raw_project_name.strip())
|
|
11546
|
+
and _FEEDBACK_SEMVER_RE.fullmatch(skill_version)
|
|
11547
|
+
and (repo / "docs" / "skill-feedback" / "reports").exists()
|
|
11548
|
+
):
|
|
11549
|
+
try:
|
|
11550
|
+
feedback = _feedback_collection_result([str(repo)])
|
|
11551
|
+
except APError:
|
|
11552
|
+
advisories.append(
|
|
11553
|
+
"Skill feedback metadata needs maintenance; run "
|
|
11554
|
+
"autocoding feedback --projects . --json for the bounded diagnostic"
|
|
11555
|
+
)
|
|
11556
|
+
else:
|
|
11557
|
+
if feedback["action_required_count"]:
|
|
11558
|
+
advisories.append(
|
|
11559
|
+
f"{feedback['action_required_count']} Skill feedback report(s) need recheck, "
|
|
11560
|
+
"closure, upgrade, or project-overlay routing; run "
|
|
11561
|
+
"autocoding feedback --projects . --json"
|
|
11562
|
+
)
|
|
11563
|
+
|
|
9188
11564
|
missing.extend(validation_errors)
|
|
9189
11565
|
|
|
9190
11566
|
if missing:
|
|
9191
|
-
|
|
11567
|
+
if record:
|
|
11568
|
+
_record_evidence(repo, cfg, "doctor", "fail", {"issues": missing})
|
|
11569
|
+
if collect:
|
|
11570
|
+
return {"issues": missing, "advisories": advisories}
|
|
9192
11571
|
raise APError("Doctor found blocking config issues:\n- " + "\n- ".join(missing))
|
|
9193
11572
|
|
|
9194
|
-
|
|
9195
|
-
|
|
9196
|
-
|
|
9197
|
-
|
|
9198
|
-
|
|
9199
|
-
|
|
9200
|
-
|
|
9201
|
-
|
|
9202
|
-
|
|
9203
|
-
|
|
11573
|
+
if record:
|
|
11574
|
+
_record_evidence(
|
|
11575
|
+
repo,
|
|
11576
|
+
cfg,
|
|
11577
|
+
"doctor",
|
|
11578
|
+
"pass",
|
|
11579
|
+
{"mode": mode, "completion": completion, "access_fields": len(_REQUIRED_ACCESS_FIELDS)},
|
|
11580
|
+
)
|
|
11581
|
+
if collect:
|
|
11582
|
+
return {"issues": [], "advisories": advisories}
|
|
11583
|
+
if not quiet:
|
|
11584
|
+
for advisory in advisories:
|
|
11585
|
+
print(f"[doctor] WARN: {advisory}")
|
|
11586
|
+
print("[doctor] OK")
|
|
11587
|
+
return None
|
|
9204
11588
|
|
|
9205
11589
|
|
|
9206
11590
|
def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
|
|
@@ -10456,6 +12840,9 @@ def cmd_task_start(args: argparse.Namespace) -> None:
|
|
|
10456
12840
|
or getattr(args, "force_lifecycle", False)
|
|
10457
12841
|
or continue_direct
|
|
10458
12842
|
)
|
|
12843
|
+
# Validate legacy workflow policy before planning reads gate/risk rules so
|
|
12844
|
+
# task-start reports the complete migration set and remains zero-write.
|
|
12845
|
+
_require_workflow_policy_clean(repo, cfg)
|
|
10459
12846
|
preflight_plan = _resolve_execution_plan(
|
|
10460
12847
|
cfg,
|
|
10461
12848
|
repo,
|
|
@@ -10478,12 +12865,11 @@ def cmd_task_start(args: argparse.Namespace) -> None:
|
|
|
10478
12865
|
"only when classify requires isolation/review or the user explicitly requests it."
|
|
10479
12866
|
)
|
|
10480
12867
|
|
|
10481
|
-
_require_workflow_policy_clean(repo, cfg)
|
|
10482
12868
|
configured_isolation = _task_isolation(cfg)
|
|
10483
12869
|
access_issues = _access_config_issues(cfg)
|
|
10484
12870
|
if access_issues:
|
|
10485
12871
|
raise APError(
|
|
10486
|
-
"Project initialization is incomplete; fill docs/
|
|
12872
|
+
"Project initialization is incomplete; fill docs/project/auto-coding-skill.yaml before starting work:\n- "
|
|
10487
12873
|
+ "\n- ".join(access_issues)
|
|
10488
12874
|
)
|
|
10489
12875
|
remote, target_branch, base_ref = _task_remote_and_target(cfg, args)
|
|
@@ -13746,6 +16132,12 @@ def main(argv: Optional[List[str]] = None) -> int:
|
|
|
13746
16132
|
s.add_argument("--json", action="store_true")
|
|
13747
16133
|
s.set_defaults(func=cmd_scaffold)
|
|
13748
16134
|
|
|
16135
|
+
s = sp.add_parser("managed-scaffold-converge", help=argparse.SUPPRESS)
|
|
16136
|
+
s.add_argument("group", choices=scaffold_groups())
|
|
16137
|
+
s.add_argument("--write", action="store_true")
|
|
16138
|
+
s.add_argument("--json", action="store_true")
|
|
16139
|
+
s.set_defaults(func=cmd_managed_scaffold_converge)
|
|
16140
|
+
|
|
13749
16141
|
s = sp.add_parser("upgrade")
|
|
13750
16142
|
s.add_argument("--dry-run", action="store_true")
|
|
13751
16143
|
s.add_argument("--write", action="store_true")
|
|
@@ -13757,6 +16149,49 @@ def main(argv: Optional[List[str]] = None) -> int:
|
|
|
13757
16149
|
s.add_argument("--json", action="store_true")
|
|
13758
16150
|
s.set_defaults(func=cmd_project_converge)
|
|
13759
16151
|
|
|
16152
|
+
s = sp.add_parser("project-config-prepare", help=argparse.SUPPRESS)
|
|
16153
|
+
s.add_argument("--write", action="store_true")
|
|
16154
|
+
s.add_argument("--json", action="store_true")
|
|
16155
|
+
s.set_defaults(func=cmd_project_config_prepare)
|
|
16156
|
+
|
|
16157
|
+
s = sp.add_parser("project-config-finalize", help=argparse.SUPPRESS)
|
|
16158
|
+
s.add_argument("--write", action="store_true")
|
|
16159
|
+
s.add_argument("--json", action="store_true")
|
|
16160
|
+
s.add_argument("--engineering-sha256", required=True)
|
|
16161
|
+
s.add_argument("--overlay-sha256", required=True)
|
|
16162
|
+
s.add_argument("--template-sha256", required=True)
|
|
16163
|
+
s.set_defaults(func=cmd_project_config_finalize)
|
|
16164
|
+
|
|
16165
|
+
s = sp.add_parser("project-file-safe", help=argparse.SUPPRESS)
|
|
16166
|
+
s.add_argument("operation", choices=["write", "create", "chmod", "chmod-batch"])
|
|
16167
|
+
s.add_argument("--path", default="")
|
|
16168
|
+
s.add_argument("--mode", default="")
|
|
16169
|
+
s.add_argument("--json", action="store_true")
|
|
16170
|
+
s.set_defaults(func=cmd_project_file_safe)
|
|
16171
|
+
|
|
16172
|
+
s = sp.add_parser("install-io", help=argparse.SUPPRESS)
|
|
16173
|
+
s.add_argument("operation", choices=["switch", "recover", "complete"])
|
|
16174
|
+
s.add_argument("--old-skill-present", action="store_true")
|
|
16175
|
+
s.add_argument("--old-manifest-present", action="store_true")
|
|
16176
|
+
s.add_argument("--old-engineering-present", action="store_true")
|
|
16177
|
+
s.add_argument("--json", action="store_true")
|
|
16178
|
+
s.set_defaults(func=cmd_install_io)
|
|
16179
|
+
|
|
16180
|
+
s = sp.add_parser(
|
|
16181
|
+
"config-effective",
|
|
16182
|
+
help="Show a redacted summary of managed defaults plus project overrides",
|
|
16183
|
+
)
|
|
16184
|
+
s.add_argument("--json", action="store_true")
|
|
16185
|
+
s.set_defaults(func=cmd_config_effective)
|
|
16186
|
+
|
|
16187
|
+
s = sp.add_parser(
|
|
16188
|
+
"feedback-collect",
|
|
16189
|
+
help="Read bounded metadata-only Skill feedback reports from explicit projects",
|
|
16190
|
+
)
|
|
16191
|
+
s.add_argument("--project", action="append", required=True)
|
|
16192
|
+
s.add_argument("--json", action="store_true")
|
|
16193
|
+
s.set_defaults(func=cmd_feedback_collect)
|
|
16194
|
+
|
|
13760
16195
|
s = sp.add_parser("baseline")
|
|
13761
16196
|
baseline_sp = s.add_subparsers(dest="baseline_cmd", required=True)
|
|
13762
16197
|
b = baseline_sp.add_parser("init")
|
|
@@ -14060,6 +16495,24 @@ def main(argv: Optional[List[str]] = None) -> int:
|
|
|
14060
16495
|
|
|
14061
16496
|
try:
|
|
14062
16497
|
args = p.parse_args(argv)
|
|
16498
|
+
repo = Path(args.repo).resolve()
|
|
16499
|
+
tokenized_write = (
|
|
16500
|
+
args.cmd == "project-file-safe"
|
|
16501
|
+
or (
|
|
16502
|
+
args.cmd in {
|
|
16503
|
+
"managed-scaffold-converge",
|
|
16504
|
+
"project-config-finalize",
|
|
16505
|
+
"project-converge",
|
|
16506
|
+
}
|
|
16507
|
+
and bool(getattr(args, "write", False))
|
|
16508
|
+
)
|
|
16509
|
+
)
|
|
16510
|
+
if args.cmd == "install-io":
|
|
16511
|
+
pass
|
|
16512
|
+
elif tokenized_write:
|
|
16513
|
+
_require_active_install_transaction(repo)
|
|
16514
|
+
elif args.cmd != "config-effective":
|
|
16515
|
+
_require_no_install_transaction(repo)
|
|
14063
16516
|
args.func(args)
|
|
14064
16517
|
return 0
|
|
14065
16518
|
except APError as e:
|