@elvis1513/auto-coding-skill 2.0.2 → 2.0.4

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 CHANGED
@@ -23,6 +23,19 @@ npm install -g git+https://github.com/elvis1513/auto-coding-skill.git
23
23
 
24
24
  ## Release Notes
25
25
 
26
+ ### v2.0.4
27
+
28
+ - Added a generic impact-aware gate engine: `ap.py impact`, `light-gate --scope auto|changed|standard|full`, and `--explain`.
29
+ - Added project-owned `gate.*` policy support in `docs/ENGINEERING.md`; the skill chooses scope, while each project declares its own commands and optional path rules.
30
+ - Kept backward compatibility: projects without `gate.*` continue to use the existing standard `commands.light_gate` / quick-test fallback.
31
+ - Added conservative full-gate upgrades for CI, deploy, Docker, lockfile, build-tool, and autopipeline config changes.
32
+
33
+ ### v2.0.3
34
+
35
+ - Fixed `doctor`, `light-gate`, `verify-target`, and Jenkins API verification to accept secret references via `*_password_env`.
36
+ - Kept direct `*_password` fields compatible for legacy projects while making the default template use environment-variable secret references.
37
+ - Updated docs so `docs/ENGINEERING.md` can stay Git-tracked without requiring committed secrets.
38
+
26
39
  ### v2.0.2
27
40
 
28
41
  - Added default Codex subagent templates under `.agents/agents`.
@@ -142,6 +155,7 @@ It must be committed to Git. Do not add it to `.gitignore`.
142
155
  重点字段:
143
156
  - `workflow.mode`
144
157
  - `commands.*`
158
+ - `gate.*`
145
159
  - `target_env.*`
146
160
  - `jenkins.*`
147
161
  - `docs.*`
@@ -149,23 +163,23 @@ It must be committed to Git. Do not add it to `.gitignore`.
149
163
  默认必填:
150
164
  - `workflow.mode`
151
165
  - `project.name`
152
- - `commands.light_gate` 或 `commands.quick_test` 或 `commands.test` 或 `commands.build`
166
+ - `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`,或 `commands.light_gate` / `commands.quick_test` / `commands.test` / `commands.build`
153
167
  - `target_env.name`
154
168
  - `target_env.frontend_base_url`
155
169
  - `target_env.frontend_username`
156
- - `target_env.frontend_password`
170
+ - `target_env.frontend_password` 或 `target_env.frontend_password_env`
157
171
  - `target_env.backend_base_url`
158
172
  - `target_env.backend_username`
159
- - `target_env.backend_password`
173
+ - `target_env.backend_password` 或 `target_env.backend_password_env`
160
174
  - `target_env.backend_root_username`
161
- - `target_env.backend_root_password`
175
+ - `target_env.backend_root_password` 或 `target_env.backend_root_password_env`
162
176
  - `target_env.health_base_url`
163
177
  - `target_env.health_path`
164
178
  - `jenkins.base_url`
165
179
  - `jenkins.ui_username`
166
- - `jenkins.ui_password`
180
+ - `jenkins.ui_password` 或 `jenkins.ui_password_env`
167
181
  - `jenkins.api_user`
168
- - `jenkins.api_password`
182
+ - `jenkins.api_password` 或 `jenkins.api_password_env`
169
183
  - `jenkins.trigger_branch`
170
184
  - `jenkins.image_repository`
171
185
  - `jenkins.image_tag_strategy`
@@ -229,6 +243,10 @@ It must be committed to Git. Do not add it to `.gitignore`.
229
243
 
230
244
  ## Default Gate Policy
231
245
  - Default local gate is lightweight only.
246
+ - Use `python3 docs/tools/autopipeline/ap.py impact --scope auto` to inspect changed files, matched project rules, and selected gate scope.
247
+ - Use `python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain` for small-step development after a project declares `gate.default_scope: auto`, `commands.gate_changed`, or matching `gate.rules`.
248
+ - Use `light-gate --scope standard` for the backward-compatible configured gate, and `light-gate --scope full` before release/deploy-sensitive closure.
249
+ - The gate engine is generic. Project-specific path mapping belongs in `docs/ENGINEERING.md` under `gate.rules`; unknown or high-risk impact should upgrade to standard/full rather than silently skipping checks.
232
250
  - Do not require local Docker Compose or full local regression unless the task explicitly needs local runtime diagnosis.
233
251
  - In `dev` mode, push is the finish line after `DEV-CLOSED` is recorded.
234
252
  - In `verify` mode, Jenkins success, target environment verification, and closure record are mandatory.
@@ -240,10 +258,11 @@ It must be committed to Git. Do not add it to `.gitignore`.
240
258
  - Purpose: single source of project config + workflow rules.
241
259
  - How to record:
242
260
  - Fill YAML frontmatter once.
243
- - Keep target env front/backend usernames and passwords, Jenkins UI/API usernames and passwords, commands, docs paths here only.
261
+ - Keep target env front/backend usernames, Jenkins UI/API usernames, password fields or `*_password_env` references, commands, and docs paths here only.
244
262
  - Target environment also includes backend server root username/password.
245
- - This file is expected to be committed to Git and maintained in plaintext for this workflow.
263
+ - This file is expected to be committed to Git; prefer `*_password_env` for secrets so actual secret values stay in the current shell.
246
264
  - Remaining environment keys are all mandatory; blank values, TODO-like placeholders, and incorrect URL/path formats are treated as blocking errors by `doctor`.
265
+ - For secret fields, `doctor` requires either a direct `*_password` value or a `*_password_env` variable name. Commands that actually authenticate require the referenced environment variable to be set at execution time.
247
266
  - Do not duplicate config elsewhere.
248
267
 
249
268
  ### 2) docs/tasks/taskbook.md
@@ -7,7 +7,7 @@ description: Use for a Claude/Codex engineering workflow with dev and verify mod
7
7
 
8
8
  This skill is for Go backend + frontend monorepo projects that rely on Jenkins to build and deploy after push. It supports both Claude and Codex. The default `dev` mode is optimized for fast development: lightweight local gate, early closure record, commit, push, then move to the next task. Use `verify` mode when Jenkins and the real target environment must be completed before closure.
9
9
 
10
- `docs/ENGINEERING.md` is intentionally Git-tracked in this workflow. The remaining environment fields in that file are mandatory, must be filled with real values, and are committed as part of the project baseline. Unused environment keys should be removed from the template instead of being left as placeholders.
10
+ `docs/ENGINEERING.md` is intentionally Git-tracked in this workflow. The remaining environment fields in that file are mandatory, must be filled with real values, and are committed as part of the project baseline. Secret fields may be represented either as direct `*_password` values for legacy projects or as `*_password_env` names that point to environment variables in the current shell. Unused environment keys should be removed from the template instead of being left as placeholders.
11
11
 
12
12
  At task start, inventory the current client capabilities before choosing a route: installed MCP servers, local skills, plugins/apps/connectors, browser/control tools, and repo scripts. Prefer those capabilities when they provide current, authoritative, or directly inspectable state.
13
13
 
@@ -78,6 +78,7 @@ Fill only:
78
78
  This contains all manual fields:
79
79
  - `workflow.mode`
80
80
  - `commands.*`
81
+ - `gate.*`
81
82
  - `runtime.*` (only for optional local diagnostics)
82
83
  - `target_env.*`
83
84
  - `jenkins.*`
@@ -89,23 +90,23 @@ Do not hide `docs/ENGINEERING.md` in `.gitignore`.
89
90
  Minimum required config for the default flow:
90
91
  - `workflow.mode`
91
92
  - `project.name`
92
- - `commands.light_gate` or `commands.quick_test` or `commands.test` or `commands.build`
93
+ - `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`, or `commands.light_gate` / `commands.quick_test` / `commands.test` / `commands.build`
93
94
  - `target_env.name`
94
95
  - `target_env.frontend_base_url`
95
96
  - `target_env.frontend_username`
96
- - `target_env.frontend_password`
97
+ - `target_env.frontend_password` or `target_env.frontend_password_env`
97
98
  - `target_env.backend_base_url`
98
99
  - `target_env.backend_username`
99
- - `target_env.backend_password`
100
+ - `target_env.backend_password` or `target_env.backend_password_env`
100
101
  - `target_env.backend_root_username`
101
- - `target_env.backend_root_password`
102
+ - `target_env.backend_root_password` or `target_env.backend_root_password_env`
102
103
  - `target_env.health_base_url`
103
104
  - `target_env.health_path`
104
105
  - `jenkins.base_url`
105
106
  - `jenkins.ui_username`
106
- - `jenkins.ui_password`
107
+ - `jenkins.ui_password` or `jenkins.ui_password_env`
107
108
  - `jenkins.api_user`
108
- - `jenkins.api_password`
109
+ - `jenkins.api_password` or `jenkins.api_password_env`
109
110
  - `jenkins.trigger_branch`
110
111
  - `jenkins.image_repository`
111
112
  - `jenkins.image_tag_strategy`
@@ -149,6 +150,9 @@ Default commands:
149
150
 
150
151
  ```bash
151
152
  python3 docs/tools/autopipeline/ap.py doctor
153
+ python3 docs/tools/autopipeline/ap.py impact --scope auto
154
+ python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
155
+ python3 docs/tools/autopipeline/ap.py light-gate --scope full
152
156
  python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
153
157
  python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --mode dev --msg "<TASK_ID>: <summary>"
154
158
  python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --mode verify --msg "<TASK_ID>: <summary>" --backend-path /health --frontend-path /
@@ -167,6 +171,9 @@ python3 docs/tools/autopipeline/ap.py gen-summary <TASK_ID>
167
171
  ## Quality policy
168
172
 
169
173
  - Default local gate is lightweight and time-bounded: prefer one curated project command via `commands.light_gate`, then run only diff/API/Jenkins checks.
174
+ - For small-step development, prefer the generic impact-aware gate: `light-gate --scope auto`. The skill provides the gate engine; each project owns its commands and optional `gate.rules` path mapping in `docs/ENGINEERING.md`.
175
+ - Keep `standard` as the backward-compatible default when no `gate.*` policy is configured. Use `changed` only when project commands/rules make the reduced scope explicit.
176
+ - Automatically upgrade to `full` for CI/deploy/build-tool/lockfile/autopipeline config changes, project-declared full rules, unknown impact when configured, or release/verify tasks.
170
177
  - `workflow.mode: dev` closes development after light gate, closure record, commit, and push.
171
178
  - `workflow.mode: verify` closes only after Jenkins and target-environment verification.
172
179
  - `doctor` should be used early to catch missing or invalid config before the first implementation loop.
@@ -13,6 +13,9 @@ project:
13
13
  jenkinsfile: "Jenkinsfile"
14
14
 
15
15
  commands:
16
+ gate_changed: ""
17
+ gate_standard: ""
18
+ gate_full: ""
16
19
  light_gate: ""
17
20
  build: ""
18
21
  test: ""
@@ -21,6 +24,35 @@ commands:
21
24
  typecheck: ""
22
25
  format: ""
23
26
 
27
+ gate:
28
+ default_scope: "standard"
29
+ fallback_scope: "standard"
30
+ full_on_unknown: true
31
+ no_change_scope: "standard"
32
+ full_on:
33
+ paths:
34
+ - "Jenkinsfile"
35
+ - "Jenkinsfile.*"
36
+ - ".github/workflows/**"
37
+ - "Dockerfile"
38
+ - "**/Dockerfile"
39
+ - "docker-compose*.yml"
40
+ - "docker-compose*.yaml"
41
+ - "compose*.yml"
42
+ - "compose*.yaml"
43
+ - "docs/ENGINEERING.md"
44
+ - "docs/tools/autopipeline/**"
45
+ - "package-lock.json"
46
+ - "pnpm-lock.yaml"
47
+ - "yarn.lock"
48
+ - "go.mod"
49
+ - "go.sum"
50
+ - "Cargo.lock"
51
+ - "pom.xml"
52
+ - "build.gradle*"
53
+ - "settings.gradle*"
54
+ rules: []
55
+
24
56
  runtime:
25
57
  docker_compose_file: ""
26
58
  docker_service: ""
@@ -33,19 +65,19 @@ target_env:
33
65
  name: ""
34
66
  frontend_base_url: ""
35
67
  frontend_username: ""
36
- frontend_password: ""
68
+ frontend_password_env: ""
37
69
  backend_base_url: ""
38
70
  backend_username: ""
39
- backend_password: ""
71
+ backend_password_env: ""
40
72
  backend_root_username: ""
41
- backend_root_password: ""
73
+ backend_root_password_env: ""
42
74
  health_base_url: ""
43
75
  health_path: ""
44
76
 
45
77
  jenkins:
46
78
  base_url: ""
47
79
  ui_username: ""
48
- ui_password: ""
80
+ ui_password_env: ""
49
81
  job_url: ""
50
82
  trigger_branch: ""
51
83
  image_repository: ""
@@ -53,7 +85,7 @@ jenkins:
53
85
  deploy_env: ""
54
86
  deploy_timeout_sec: 1800
55
87
  api_user: ""
56
- api_password: ""
88
+ api_password_env: ""
57
89
 
58
90
  docs:
59
91
  taskbook: "docs/tasks/taskbook.md"
@@ -87,7 +119,7 @@ docs:
87
119
  - 每次任务闭环后,必须清理临时文件、临时目录、日志、截图、构建缓存等非必要产物;仅明确需要保留的本地诊断目录允许保留。
88
120
  - 所有手工填写信息,只维护在本文件 frontmatter 中,其他文档不得重复配置。
89
121
  - `docs/ENGINEERING.md` 必须提交到 Git 管理,不允许写入 `.gitignore`。
90
- - 本 workflow 明确允许在 `docs/ENGINEERING.md` 中明文维护平台账号、密码,并随 Git 一起版本化。
122
+ - 目标环境和 Jenkins 密码默认通过 `*_password_env` 指向当前 shell 中的环境变量;确需兼容旧项目时才使用明文 `*_password` 字段。
91
123
  - 未参与默认流程的环境项不要保留占位;模板中未保留的字段视为已清理,不再额外配置。
92
124
 
93
125
  ---
@@ -96,37 +128,38 @@ docs:
96
128
 
97
129
  先填写 `docs/ENGINEERING.md` frontmatter 中的所有空值。重点包括:
98
130
  - `workflow.mode`:`dev` 或 `verify`,默认推荐 `dev`
99
- - `commands.light_gate`:推荐配置一个项目级快速门禁命令,作为默认本地校验入口
100
- - `target_env.*`:目标环境前端 / 后端地址、用户名、密码,必须全部填写且真实可用
101
- - `jenkins.*`:Jenkins UI/API 用户名、密码、Job、分支、镜像、部署环境,必须全部填写且真实可用
131
+ - `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`:推荐配置分层门禁命令;旧项目也可以继续只配置 `commands.light_gate`
132
+ - `gate.*`:按项目声明路径规则和高风险升级规则;未配置时保持标准门禁行为
133
+ - `target_env.*`:目标环境前端 / 后端地址、用户名、密码引用,必须全部填写且真实可用
134
+ - `jenkins.*`:Jenkins UI/API 用户名、密码引用、Job、分支、镜像、部署环境,必须全部填写且真实可用
102
135
 
103
136
  字段说明:
104
- - `target_env.backend_username` / `target_env.backend_password`:目标环境后台账号
105
- - `target_env.backend_root_username` / `target_env.backend_root_password`:目标环境后台服务器 root 账号
106
- - `target_env.frontend_username` / `target_env.frontend_password`:目标环境前端登录账号
107
- - `jenkins.ui_username` / `jenkins.ui_password`:Jenkins 页面登录账号
108
- - `jenkins.api_user` / `jenkins.api_password`:Jenkins API 用户名 / 密码
137
+ - `target_env.backend_username` + `target_env.backend_password_env` 或 `target_env.backend_password`:目标环境后台账号
138
+ - `target_env.backend_root_username` + `target_env.backend_root_password_env` 或 `target_env.backend_root_password`:目标环境后台服务器 root 账号
139
+ - `target_env.frontend_username` + `target_env.frontend_password_env` 或 `target_env.frontend_password`:目标环境前端登录账号
140
+ - `jenkins.ui_username` + `jenkins.ui_password_env` 或 `jenkins.ui_password`:Jenkins 页面登录账号
141
+ - `jenkins.api_user` + `jenkins.api_password_env` 或 `jenkins.api_password`:Jenkins API 用户名 / 密码
109
142
 
110
143
  默认必填:
111
144
  - `workflow.mode`
112
145
  - `project.name`
113
- - `commands.light_gate` 或 `commands.quick_test` 或 `commands.test` 或 `commands.build`
146
+ - `commands.gate_changed` / `commands.gate_standard` / `commands.gate_full`,或 `commands.light_gate` / `commands.quick_test` / `commands.test` / `commands.build`
114
147
  - `target_env.name`
115
148
  - `target_env.frontend_base_url`
116
149
  - `target_env.frontend_username`
117
- - `target_env.frontend_password`
150
+ - `target_env.frontend_password` 或 `target_env.frontend_password_env`
118
151
  - `target_env.backend_base_url`
119
152
  - `target_env.backend_username`
120
- - `target_env.backend_password`
153
+ - `target_env.backend_password` 或 `target_env.backend_password_env`
121
154
  - `target_env.backend_root_username`
122
- - `target_env.backend_root_password`
155
+ - `target_env.backend_root_password` 或 `target_env.backend_root_password_env`
123
156
  - `target_env.health_base_url`
124
157
  - `target_env.health_path`
125
158
  - `jenkins.base_url`
126
159
  - `jenkins.ui_username`
127
- - `jenkins.ui_password`
160
+ - `jenkins.ui_password` 或 `jenkins.ui_password_env`
128
161
  - `jenkins.api_user`
129
- - `jenkins.api_password`
162
+ - `jenkins.api_password` 或 `jenkins.api_password_env`
130
163
  - `jenkins.trigger_branch`
131
164
  - `jenkins.image_repository`
132
165
  - `jenkins.image_tag_strategy`
@@ -134,6 +167,8 @@ docs:
134
167
  - `jenkins.job_url`
135
168
 
136
169
  按需填写:
170
+ - `gate.default_scope`:默认 `standard`;需要小步快跑时设为 `auto` 或 `changed`
171
+ - `gate.rules`:项目自定义路径规则。每条规则可包含 `name`、`paths`、`commands`、`scope`
137
172
  - `runtime.*`:仅在本地运行诊断时使用
138
173
  - `commands.build` / `commands.test` / `commands.quick_test` / `commands.lint` / `commands.typecheck` / `commands.format`:按项目实际情况保留
139
174
 
@@ -7,7 +7,9 @@ from __future__ import annotations
7
7
  import argparse
8
8
  import base64
9
9
  import datetime as _dt
10
+ import fnmatch
10
11
  import json
12
+ import os
11
13
  import time
12
14
  import urllib.parse
13
15
  import urllib.error
@@ -60,23 +62,32 @@ def _run_configured_command(repo: Path, cfg: dict, name: str) -> bool:
60
62
 
61
63
  def _jenkins_basic_auth_headers(cfg: dict) -> dict:
62
64
  jenkins_cfg = (cfg.get("jenkins") or {})
63
- user_candidates = [
64
- jenkins_cfg.get("api_user"),
65
- jenkins_cfg.get("ui_username"),
65
+ credential_pairs = [
66
+ ("api_user", "api_password"),
67
+ ("ui_username", "ui_password"),
66
68
  ]
67
- secret_candidates = [
68
- jenkins_cfg.get("api_password"),
69
- jenkins_cfg.get("ui_password"),
70
- ]
71
- user = next((_text(v) for v in user_candidates if _is_explicit_fill(v)), "")
72
- secret = next((_text(v) for v in secret_candidates if _is_explicit_fill(v)), "")
73
- if not user or not secret:
74
- raise APError(
75
- "Missing Jenkins API credentials. Fill jenkins.api_user and jenkins.api_password in docs/ENGINEERING.md."
76
- )
77
- raw = f"{user}:{secret}".encode("utf-8")
78
- auth = base64.b64encode(raw).decode("ascii")
79
- return {"Authorization": f"Basic {auth}"}
69
+ errors: list[str] = []
70
+
71
+ for user_field, secret_field in credential_pairs:
72
+ user = _text(jenkins_cfg.get(user_field))
73
+ if not _is_explicit_fill(user):
74
+ continue
75
+ try:
76
+ secret = _resolve_secret("jenkins", jenkins_cfg, secret_field)
77
+ except APError as exc:
78
+ errors.append(str(exc))
79
+ continue
80
+ raw = f"{user}:{secret}".encode("utf-8")
81
+ auth = base64.b64encode(raw).decode("ascii")
82
+ return {"Authorization": f"Basic {auth}"}
83
+
84
+ detail = "\n- " + "\n- ".join(errors) if errors else ""
85
+ raise APError(
86
+ "Missing Jenkins API credentials. Configure jenkins.api_user with "
87
+ "jenkins.api_password or jenkins.api_password_env, or configure "
88
+ "jenkins.ui_username with jenkins.ui_password or jenkins.ui_password_env."
89
+ + detail
90
+ )
80
91
 
81
92
 
82
93
  def _http_error_body(exc: urllib.error.HTTPError) -> str:
@@ -593,6 +604,331 @@ def _require_explicit_field(missing: List[str], field: str, value: object) -> No
593
604
  missing.append(f"{field} (must be explicitly filled, not blank/TODO)")
594
605
 
595
606
 
607
+ def _has_secret_reference(section_cfg: dict, field: str) -> bool:
608
+ return _is_explicit_fill(section_cfg.get(field)) or _is_explicit_fill(section_cfg.get(f"{field}_env"))
609
+
610
+
611
+ def _require_secret_reference(missing: List[str], section_name: str, section_cfg: dict, field: str) -> None:
612
+ if not _has_secret_reference(section_cfg, field):
613
+ missing.append(
614
+ f"{section_name}.{field} or {section_name}.{field}_env "
615
+ "(must be explicitly filled, not blank/TODO)"
616
+ )
617
+
618
+
619
+ def _resolve_secret(section_name: str, section_cfg: dict, field: str) -> str:
620
+ direct_value = section_cfg.get(field)
621
+ if _is_explicit_fill(direct_value):
622
+ return _text(direct_value)
623
+
624
+ env_field = f"{field}_env"
625
+ env_name = _text(section_cfg.get(env_field))
626
+ if _is_explicit_fill(env_name):
627
+ env_value = os.environ.get(env_name, "")
628
+ if _is_explicit_fill(env_value):
629
+ return _text(env_value)
630
+ raise APError(
631
+ f"Missing secret value for {section_name}.{field}. "
632
+ f"Set environment variable {env_name} declared by {section_name}.{env_field}, "
633
+ f"or fill {section_name}.{field}."
634
+ )
635
+
636
+ raise APError(
637
+ f"Missing {section_name}.{field}. Fill {section_name}.{field} "
638
+ f"or declare {section_name}.{env_field}."
639
+ )
640
+
641
+
642
+ _GATE_SCOPES = {"auto", "changed", "standard", "full"}
643
+ _DOC_PATH_PATTERNS = ["*.md", "docs/**"]
644
+ _DEFAULT_FULL_PATH_PATTERNS = [
645
+ ".agents/**",
646
+ ".claude/**",
647
+ ".github/workflows/**",
648
+ "Jenkinsfile",
649
+ "Jenkinsfile.*",
650
+ "Dockerfile",
651
+ "**/Dockerfile",
652
+ "docker-compose*.yml",
653
+ "docker-compose*.yaml",
654
+ "compose*.yml",
655
+ "compose*.yaml",
656
+ "docs/ENGINEERING.md",
657
+ "docs/tools/autopipeline/**",
658
+ "package-lock.json",
659
+ "pnpm-lock.yaml",
660
+ "yarn.lock",
661
+ "bun.lockb",
662
+ "go.mod",
663
+ "go.sum",
664
+ "Cargo.lock",
665
+ "pom.xml",
666
+ "build.gradle",
667
+ "build.gradle.kts",
668
+ "settings.gradle",
669
+ "settings.gradle.kts",
670
+ ]
671
+
672
+
673
+ def _gate_cfg(cfg: dict) -> dict:
674
+ gate_cfg = cfg.get("gate") or {}
675
+ return gate_cfg if isinstance(gate_cfg, dict) else {}
676
+
677
+
678
+ def _as_list(value: object) -> list:
679
+ if value is None:
680
+ return []
681
+ if isinstance(value, list):
682
+ return value
683
+ return [value]
684
+
685
+
686
+ def _command_name(ref: object) -> str:
687
+ raw = _text(ref)
688
+ if raw.startswith("commands."):
689
+ raw = raw.split(".", 1)[1]
690
+ return raw
691
+
692
+
693
+ def _configured_command(cfg: dict, name: str) -> str:
694
+ commands = cfg.get("commands") or {}
695
+ return _text(commands.get(name))
696
+
697
+
698
+ def _run_first_configured_command(repo: Path, cfg: dict, names: list[str]) -> str:
699
+ for name in names:
700
+ command_name = _command_name(name)
701
+ if command_name and _configured_command(cfg, command_name):
702
+ _run_configured_command(repo, cfg, command_name)
703
+ return command_name
704
+ return ""
705
+
706
+
707
+ def _run_configured_command_list(repo: Path, cfg: dict, names: list) -> list[str]:
708
+ executed: list[str] = []
709
+ missing: list[str] = []
710
+ for name_ref in names:
711
+ name = _command_name(name_ref)
712
+ if not name:
713
+ continue
714
+ if _configured_command(cfg, name):
715
+ _run_configured_command(repo, cfg, name)
716
+ executed.append(name)
717
+ else:
718
+ missing.append(name)
719
+ if missing and not executed:
720
+ raise APError("Gate rule references missing commands: " + ", ".join(missing))
721
+ return executed
722
+
723
+
724
+ def _path_matches(path: str, patterns: list) -> bool:
725
+ normalized = path.replace("\\", "/").lstrip("./")
726
+ for pattern_ref in patterns:
727
+ pattern = _text(pattern_ref).replace("\\", "/").lstrip("./")
728
+ if not pattern:
729
+ continue
730
+ if fnmatch.fnmatch(normalized, pattern):
731
+ return True
732
+ if "/" not in pattern and fnmatch.fnmatch(Path(normalized).name, pattern):
733
+ return True
734
+ return False
735
+
736
+
737
+ def _unique_paths(paths: list[str]) -> list[str]:
738
+ seen = set()
739
+ out = []
740
+ for path in paths:
741
+ normalized = path.replace("\\", "/").strip()
742
+ if not normalized or normalized in seen:
743
+ continue
744
+ seen.add(normalized)
745
+ out.append(normalized)
746
+ return sorted(out)
747
+
748
+
749
+ def _git_lines(repo: Path, cmd: list[str]) -> list[str]:
750
+ try:
751
+ result = run(cmd, cwd=repo, check=False)
752
+ except APError:
753
+ return []
754
+ if result.returncode != 0:
755
+ return []
756
+ return [line.strip() for line in result.stdout.splitlines() if line.strip()]
757
+
758
+
759
+ def _default_base_ref(repo: Path) -> str:
760
+ upstream = _git_lines(repo, ["git", "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"])
761
+ return upstream[0] if upstream else ""
762
+
763
+
764
+ def _changed_files(repo: Path, base_ref: str = "") -> list[str]:
765
+ paths: list[str] = []
766
+ effective_base = base_ref or _default_base_ref(repo)
767
+ if effective_base:
768
+ paths.extend(_git_lines(repo, ["git", "diff", "--name-only", "--diff-filter=ACMRTUXB", f"{effective_base}...HEAD"]))
769
+ paths.extend(_git_lines(repo, ["git", "diff", "--name-only", "--diff-filter=ACMRTUXB"]))
770
+ paths.extend(_git_lines(repo, ["git", "diff", "--cached", "--name-only", "--diff-filter=ACMRTUXB"]))
771
+ paths.extend(_git_lines(repo, ["git", "ls-files", "--others", "--exclude-standard"]))
772
+ return _unique_paths(paths)
773
+
774
+
775
+ def _docs_only(paths: list[str]) -> bool:
776
+ return bool(paths) and all(_path_matches(path, _DOC_PATH_PATTERNS) for path in paths)
777
+
778
+
779
+ def _gate_rules(gate_cfg: dict) -> list[dict]:
780
+ rules = gate_cfg.get("rules") or []
781
+ return [rule for rule in rules if isinstance(rule, dict)]
782
+
783
+
784
+ def _matching_gate_rules(paths: list[str], gate_cfg: dict) -> list[dict]:
785
+ matches = []
786
+ for rule in _gate_rules(gate_cfg):
787
+ patterns = _as_list(rule.get("paths"))
788
+ if patterns and any(_path_matches(path, patterns) for path in paths):
789
+ matches.append(rule)
790
+ return matches
791
+
792
+
793
+ def _gate_full_patterns(gate_cfg: dict) -> list:
794
+ full_on = gate_cfg.get("full_on") or {}
795
+ patterns = list(_DEFAULT_FULL_PATH_PATTERNS)
796
+ if isinstance(full_on, dict):
797
+ patterns.extend(_as_list(full_on.get("paths")))
798
+ else:
799
+ patterns.extend(_as_list(full_on))
800
+ return patterns
801
+
802
+
803
+ def _has_changed_gate(cfg: dict, gate_cfg: dict, paths: list[str]) -> bool:
804
+ if _configured_command(cfg, "gate_changed"):
805
+ return True
806
+ for rule in _matching_gate_rules(paths, gate_cfg):
807
+ if _as_list(rule.get("commands")):
808
+ return True
809
+ return False
810
+
811
+
812
+ def _select_gate_scope(cfg: dict, requested_scope: str, paths: list[str]) -> tuple[str, list[str], list[dict]]:
813
+ gate_cfg = _gate_cfg(cfg)
814
+ scope = (requested_scope or _text(gate_cfg.get("default_scope")) or "standard").lower()
815
+ if scope not in _GATE_SCOPES:
816
+ raise APError("gate scope must be one of: " + ", ".join(sorted(_GATE_SCOPES)))
817
+
818
+ matching_rules = _matching_gate_rules(paths, gate_cfg)
819
+ reasons: list[str] = []
820
+
821
+ if scope != "auto":
822
+ return scope, [f"requested scope: {scope}"], matching_rules
823
+
824
+ if not paths:
825
+ fallback = _text(gate_cfg.get("no_change_scope")) or "standard"
826
+ if fallback not in {"changed", "standard", "full"}:
827
+ fallback = "standard"
828
+ return fallback, ["no changed files detected"], matching_rules
829
+
830
+ rule_scopes = {_text(rule.get("scope")).lower() for rule in matching_rules if _text(rule.get("scope"))}
831
+ if "full" in rule_scopes:
832
+ return "full", ["matched gate rule with scope=full"], matching_rules
833
+ if "standard" in rule_scopes:
834
+ return "standard", ["matched gate rule with scope=standard"], matching_rules
835
+
836
+ if any(_path_matches(path, _gate_full_patterns(gate_cfg)) for path in paths):
837
+ return "full", ["changed files match full-gate patterns"], matching_rules
838
+
839
+ if _docs_only(paths):
840
+ return "changed", ["docs-only change"], matching_rules
841
+
842
+ if _has_changed_gate(cfg, gate_cfg, paths):
843
+ return "changed", ["matched changed-gate command or rule"], matching_rules
844
+
845
+ fallback = _text(gate_cfg.get("fallback_scope")) or "standard"
846
+ if fallback not in {"changed", "standard", "full"}:
847
+ fallback = "standard"
848
+ if fallback == "changed" and _text(gate_cfg.get("full_on_unknown")).lower() in {"1", "true", "yes", "on"}:
849
+ fallback = "full"
850
+ reasons.append("no changed-gate command/rule matched")
851
+ return fallback, reasons, matching_rules
852
+
853
+
854
+ def _impact_summary(cfg: dict, repo: Path, requested_scope: str, base_ref: str = "") -> dict:
855
+ paths = _changed_files(repo, base_ref=base_ref)
856
+ scope, reasons, matching_rules = _select_gate_scope(cfg, requested_scope, paths)
857
+ return {
858
+ "requested_scope": requested_scope or _text(_gate_cfg(cfg).get("default_scope")) or "standard",
859
+ "selected_scope": scope,
860
+ "reasons": reasons,
861
+ "changed_files": paths,
862
+ "matched_rules": [_text(rule.get("name")) or "(unnamed)" for rule in matching_rules],
863
+ }
864
+
865
+
866
+ def _print_impact(summary: dict, as_json: bool = False) -> None:
867
+ if as_json:
868
+ print(json.dumps(summary, ensure_ascii=False, indent=2))
869
+ return
870
+ print(f"[impact] requested_scope={summary['requested_scope']}")
871
+ print(f"[impact] selected_scope={summary['selected_scope']}")
872
+ for reason in summary.get("reasons") or []:
873
+ print(f"[impact] reason: {reason}")
874
+ for rule in summary.get("matched_rules") or []:
875
+ print(f"[impact] matched_rule: {rule}")
876
+ files = summary.get("changed_files") or []
877
+ if files:
878
+ for path in files:
879
+ print(f"[impact] changed: {path}")
880
+ else:
881
+ print("[impact] changed: (none)")
882
+
883
+
884
+ def _run_changed_gate(repo: Path, cfg: dict, paths: list[str], matching_rules: list[dict]) -> list[str]:
885
+ executed: list[str] = []
886
+ for rule in matching_rules:
887
+ executed.extend(_run_configured_command_list(repo, cfg, _as_list(rule.get("commands"))))
888
+ if executed:
889
+ return executed
890
+
891
+ fallback_commands = ["gate_changed"]
892
+ if _docs_only(paths):
893
+ fallback_commands.append("docs_check")
894
+ command = _run_first_configured_command(repo, cfg, fallback_commands)
895
+ if command:
896
+ return [command]
897
+
898
+ if _docs_only(paths):
899
+ print("[gate] docs-only change with no changed-gate command configured; running built-in post checks only.")
900
+ return ["docs_only_builtin"]
901
+
902
+ fallback = _run_first_configured_command(repo, cfg, ["quick_test", "test", "build"])
903
+ if fallback:
904
+ return [fallback]
905
+
906
+ raise APError(
907
+ "Changed gate has no configured command. Add commands.gate_changed or matching gate.rules commands, "
908
+ "or run light-gate --scope standard/full."
909
+ )
910
+
911
+
912
+ def _run_standard_gate(repo: Path, cfg: dict) -> list[str]:
913
+ command = _run_first_configured_command(repo, cfg, ["gate_standard", "light_gate", "quick_test", "test", "build"])
914
+ if not command:
915
+ raise APError(
916
+ "Standard gate is under-configured. Add commands.gate_standard, commands.light_gate, "
917
+ "commands.quick_test, commands.test, or commands.build."
918
+ )
919
+ return [command]
920
+
921
+
922
+ def _run_full_gate(repo: Path, cfg: dict) -> list[str]:
923
+ command = _run_first_configured_command(repo, cfg, ["gate_full", "full_gate", "gate_standard", "light_gate", "test", "build"])
924
+ if not command:
925
+ raise APError(
926
+ "Full gate is under-configured. Add commands.gate_full, commands.full_gate, commands.test, "
927
+ "commands.build, or commands.light_gate."
928
+ )
929
+ return [command]
930
+
931
+
596
932
  def _run_git_diff_check(repo: Path, cfg: dict) -> None:
597
933
  print("[diff-check] git diff --check")
598
934
  run(["git", "diff", "--check"], cwd=repo)
@@ -626,38 +962,35 @@ def cmd_light_gate(args: argparse.Namespace) -> None:
626
962
  repo = Path(args.repo).resolve()
627
963
  cmd_doctor(argparse.Namespace(repo=str(repo)))
628
964
  cfg = _load_cfg(repo)
629
- commands = (cfg.get("commands") or {})
630
-
631
- executed: List[str] = []
632
- missing: List[str] = []
633
-
634
- if str(commands.get("light_gate") or "").strip():
635
- _run_configured_command(repo, cfg, "light_gate")
636
- executed.append("light_gate")
637
- elif str(commands.get("quick_test") or "").strip():
638
- _run_configured_command(repo, cfg, "quick_test")
639
- executed.append("quick_test")
640
- elif str(commands.get("test") or "").strip():
641
- _run_configured_command(repo, cfg, "test")
642
- executed.append("test")
643
- elif str(commands.get("build") or "").strip():
644
- _run_configured_command(repo, cfg, "build")
645
- executed.append("build")
965
+ requested_scope = str(getattr(args, "scope", "") or "").strip().lower()
966
+ impact = _impact_summary(cfg, repo, requested_scope=requested_scope, base_ref=str(getattr(args, "base", "") or ""))
967
+ if getattr(args, "explain", False):
968
+ _print_impact(impact)
969
+
970
+ selected_scope = str(impact["selected_scope"])
971
+ paths = list(impact.get("changed_files") or [])
972
+ matching_rules = _matching_gate_rules(paths, _gate_cfg(cfg))
973
+
974
+ if selected_scope == "changed":
975
+ executed = _run_changed_gate(repo, cfg, paths, matching_rules)
976
+ elif selected_scope == "full":
977
+ executed = _run_full_gate(repo, cfg)
646
978
  else:
647
- missing.append("commands.light_gate or commands.quick_test or commands.test or commands.build")
648
-
649
- if missing:
650
- raise APError(
651
- "Light gate is under-configured. Missing required commands: "
652
- + ", ".join(missing)
653
- + ". Edit docs/ENGINEERING.md frontmatter."
654
- )
979
+ executed = _run_standard_gate(repo, cfg)
655
980
 
656
981
  _run_git_diff_check(repo, cfg)
657
982
  cmd_verify_api_docs(argparse.Namespace(repo=str(repo)))
658
983
  cmd_verify_jenkins(argparse.Namespace(repo=str(repo)))
659
984
  executed.extend(["diff_check", "verify_api_docs", "verify_jenkins"])
660
- print("[light-gate] OK: " + ", ".join(executed))
985
+ print(f"[light-gate] OK scope={selected_scope}: " + ", ".join(executed))
986
+
987
+
988
+ def cmd_impact(args: argparse.Namespace) -> None:
989
+ repo = Path(args.repo).resolve()
990
+ cfg = _load_cfg(repo)
991
+ scope = str(args.scope or "").strip().lower()
992
+ summary = _impact_summary(cfg, repo, requested_scope=scope, base_ref=str(args.base or ""))
993
+ _print_impact(summary, as_json=bool(args.json))
661
994
 
662
995
 
663
996
  def cmd_runtime_up(args: argparse.Namespace) -> None:
@@ -733,15 +1066,15 @@ def cmd_verify_target(args: argparse.Namespace) -> None:
733
1066
  frontend_headers: dict[str, str] = {}
734
1067
  if args.backend_basic_auth:
735
1068
  user = str(target_cfg.get("backend_username") or "").strip()
736
- password = str(target_cfg.get("backend_password") or "").strip()
737
- if not user or not password:
738
- raise APError("Missing target_env.backend_username / target_env.backend_password for backend basic auth.")
1069
+ if not user:
1070
+ raise APError("Missing target_env.backend_username for backend basic auth.")
1071
+ password = _resolve_secret("target_env", target_cfg, "backend_password")
739
1072
  backend_headers = _basic_auth_header(user, password)
740
1073
  if args.frontend_basic_auth:
741
1074
  user = str(target_cfg.get("frontend_username") or "").strip()
742
- password = str(target_cfg.get("frontend_password") or "").strip()
743
- if not user or not password:
744
- raise APError("Missing target_env.frontend_username / target_env.frontend_password for frontend basic auth.")
1075
+ if not user:
1076
+ raise APError("Missing target_env.frontend_username for frontend basic auth.")
1077
+ password = _resolve_secret("target_env", target_cfg, "frontend_password")
745
1078
  frontend_headers = _basic_auth_header(user, password)
746
1079
 
747
1080
  for path in args.backend_path or []:
@@ -813,34 +1146,41 @@ def cmd_doctor(args: argparse.Namespace) -> None:
813
1146
  if not str(project_cfg.get("name") or "").strip():
814
1147
  missing.append("project.name")
815
1148
  if not (
816
- str(commands.get("light_gate") or "").strip()
1149
+ str(commands.get("gate_changed") or "").strip()
1150
+ or str(commands.get("gate_standard") or "").strip()
1151
+ or str(commands.get("gate_full") or "").strip()
1152
+ or str(commands.get("full_gate") or "").strip()
1153
+ or str(commands.get("light_gate") or "").strip()
817
1154
  or str(commands.get("quick_test") or "").strip()
818
1155
  or str(commands.get("test") or "").strip()
819
1156
  or str(commands.get("build") or "").strip()
820
1157
  ):
821
- missing.append("commands.light_gate or commands.quick_test or commands.test or commands.build")
1158
+ missing.append(
1159
+ "commands.gate_changed/gate_standard/gate_full, commands.light_gate, "
1160
+ "commands.quick_test, commands.test, or commands.build"
1161
+ )
822
1162
  _require_explicit_field(missing, "target_env.name", target_cfg.get("name"))
823
1163
  _require_explicit_field(missing, "target_env.frontend_base_url", target_cfg.get("frontend_base_url"))
824
1164
  _require_explicit_field(missing, "target_env.frontend_username", target_cfg.get("frontend_username"))
825
- _require_explicit_field(missing, "target_env.frontend_password", target_cfg.get("frontend_password"))
1165
+ _require_secret_reference(missing, "target_env", target_cfg, "frontend_password")
826
1166
  _require_explicit_field(missing, "target_env.backend_base_url", target_cfg.get("backend_base_url"))
827
1167
  _require_explicit_field(missing, "target_env.backend_username", target_cfg.get("backend_username"))
828
- _require_explicit_field(missing, "target_env.backend_password", target_cfg.get("backend_password"))
1168
+ _require_secret_reference(missing, "target_env", target_cfg, "backend_password")
829
1169
  _require_explicit_field(missing, "target_env.backend_root_username", target_cfg.get("backend_root_username"))
830
- _require_explicit_field(missing, "target_env.backend_root_password", target_cfg.get("backend_root_password"))
1170
+ _require_secret_reference(missing, "target_env", target_cfg, "backend_root_password")
831
1171
  _require_explicit_field(missing, "target_env.health_base_url", target_cfg.get("health_base_url"))
832
1172
  _require_explicit_field(missing, "target_env.health_path", target_cfg.get("health_path"))
833
1173
 
834
1174
  _require_explicit_field(missing, "jenkins.base_url", jenkins_cfg.get("base_url"))
835
1175
  _require_explicit_field(missing, "jenkins.ui_username", jenkins_cfg.get("ui_username"))
836
- _require_explicit_field(missing, "jenkins.ui_password", jenkins_cfg.get("ui_password"))
1176
+ _require_secret_reference(missing, "jenkins", jenkins_cfg, "ui_password")
837
1177
  _require_explicit_field(missing, "jenkins.job_url", jenkins_cfg.get("job_url"))
838
1178
  _require_explicit_field(missing, "jenkins.trigger_branch", jenkins_cfg.get("trigger_branch"))
839
1179
  _require_explicit_field(missing, "jenkins.image_repository", jenkins_cfg.get("image_repository"))
840
1180
  _require_explicit_field(missing, "jenkins.image_tag_strategy", jenkins_cfg.get("image_tag_strategy"))
841
1181
  _require_explicit_field(missing, "jenkins.deploy_env", jenkins_cfg.get("deploy_env"))
842
1182
  _require_explicit_field(missing, "jenkins.api_user", jenkins_cfg.get("api_user"))
843
- _require_explicit_field(missing, "jenkins.api_password", jenkins_cfg.get("api_password"))
1183
+ _require_secret_reference(missing, "jenkins", jenkins_cfg, "api_password")
844
1184
 
845
1185
  repo_docs = {
846
1186
  "docs.taskbook": Path(repo, str(docs_cfg.get("taskbook", "docs/tasks/taskbook.md"))),
@@ -1211,7 +1551,16 @@ def main(argv: Optional[List[str]] = None) -> int:
1211
1551
  s.add_argument("name")
1212
1552
  s.set_defaults(func=cmd_run)
1213
1553
 
1554
+ s = sp.add_parser("impact")
1555
+ s.add_argument("--scope", choices=sorted(_GATE_SCOPES), default="")
1556
+ s.add_argument("--base")
1557
+ s.add_argument("--json", action="store_true")
1558
+ s.set_defaults(func=cmd_impact)
1559
+
1214
1560
  s = sp.add_parser("light-gate")
1561
+ s.add_argument("--scope", choices=sorted(_GATE_SCOPES), default="")
1562
+ s.add_argument("--base")
1563
+ s.add_argument("--explain", action="store_true")
1215
1564
  s.set_defaults(func=cmd_light_gate)
1216
1565
 
1217
1566
  s = sp.add_parser("doctor")
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elvis1513/auto-coding-skill",
3
- "version": "2.0.2",
3
+ "version": "2.0.4",
4
4
  "description": "CLI installer for auto-coding-skill (Claude Code + Codex CLI) with Go fullstack + Jenkins workflow support.",
5
5
  "type": "module",
6
6
  "bin": {