Files
.pouch/skills/builder/scripts/check.py
T
laily 10d8800f07 feat: add skill init/check and isolate builder makefile
Give ack, builder, and deployer an explicit init/check mode that reports
missing project config instead of failing mid-work. Point builder at
makefile.builder so its contract targets do not collide with an existing
Makefile.
2026-08-25 16:49:28 +08:00

538 lines
21 KiB
Python
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env python3
"""Executable form of the builder contract (references/contract.md).
Checks a project's makefile.builder against the contract by probing make
itself with dry runs (`make -f makefile.builder -n`) instead of parsing
makefile text: includes, conditionals, and variable expansion are resolved
by make, so behavior is what gets judged. The default Makefile/makefile is
not read.
Usage:
python3 -I -S check.py <project-dir> [--build] [--ready]
Exit codes: 0 = all PASS, 1 = at least one FAIL, 2 = usage/environment error.
`--ready` 额外检查轨道工具链和发布环境变量键名(只看键是否存在,永不打印值)。
无 makefile.builder 时普通模式退出 2`--ready` 输出结构化 FAIL 并继续工具链/发布键检查。
Change the contract here first, then mirror the change into contract.md.
"""
from __future__ import annotations
import argparse
import hashlib
import os
import re
import shutil
import subprocess
import sys
from pathlib import Path
ARCH_VALUES = ("amd64", "arm64")
REQUIRED_TARGETS = ("help", "version", "clean", "build")
UPLOAD_TOKENS = (
"curl ", "curl\t", "scp ", "rsync ", "aptly ", "reprepro ",
"docker push", "buildx build --push", "buildx --push", "upload_deb.sh",
"publish_docker.sh",
)
SECRET_PATTERNS = (
re.compile(r"(TOKEN|PASSWORD|SECRET|API_KEY|PASSWD)[A-Z_]*\s*[:?]?=\s*['\"]?[^\s$({\"']+", re.IGNORECASE),
re.compile(r"\b[A-Za-z0-9_]*token[A-Za-z0-9_]*\s*[:?]?=\s*['\"]?[A-Za-z0-9._\-]{16,}", re.IGNORECASE),
)
FLOATING_TAGS = (":latest", ":stable")
DEB_SHAPE = re.compile(r"^[^_\s]+_[^_\s]+_[^_\s]+\.deb$")
VALID_SCRIPT_NAMES = ("upload_deb.sh", "publish_docker.sh")
BUILDER_MAKEFILE = "makefile.builder"
PASS = "PASS"
FAIL = "FAIL"
SKIP = "SKIP"
class Report:
def __init__(self) -> None:
self.failures = 0
self.skips = 0
def add(self, status: str, number: int, title: str, detail: str) -> None:
print(f"[{status}] {number}. {title}")
for line in detail.splitlines():
print(f" {line}")
if status == FAIL:
self.failures += 1
elif status == SKIP:
self.skips += 0 if self.skips else 1
def run_make(
project: Path, *args: str, timeout: int = 60, dry_run: bool = True
) -> subprocess.CompletedProcess[str]:
cmd = ["make", "-C", str(project), "-f", BUILDER_MAKEFILE]
if dry_run:
cmd.append("-n")
cmd.extend(args)
return subprocess.run(
cmd, capture_output=True, text=True, timeout=timeout, check=False
)
def has_no_rule(result: subprocess.CompletedProcess[str]) -> bool:
return result.returncode != 0 and (
"No rule to make target" in result.stderr or "no rule to make target" in result.stderr.lower()
)
BANNER_RE = re.compile(r"^make(?:\[[0-9]+\])?: (进入|离开|Entering|Leaving)")
def clean_make_output(result: subprocess.CompletedProcess[str]) -> list[str]:
"""Drop make directory banners and dry-run command echoes, keep real output."""
lines = []
for line in result.stdout.splitlines():
if BANNER_RE.match(line.strip()):
continue
stripped = line.lstrip()
if stripped.startswith(("echo ", "echo\t", "printf ")):
continue
lines.append(line)
return lines
def check_required_targets(report: Report, project: Path) -> dict[str, bool]:
present: dict[str, bool] = {}
lines = []
for target in REQUIRED_TARGETS:
result = run_make(project, target)
ok = result.returncode == 0
present[target] = ok
lines.append(f"{target}: {'found' if ok else 'missing'}")
report.add(PASS if all(present.values()) else FAIL, 1, "必备目标存在(help/version/clean/build", "\n".join(lines))
return present
def check_arch_guard(report: Report, project: Path) -> None:
bad = run_make(project, "build", "ARCH=loongarch")
guard_ok = bad.returncode != 0 and ("amd64" in bad.stderr or "arm64" in bad.stderr)
default_ok = run_make(project, "build").returncode == 0
lines = [
f"invalid ARCH rejected: {'yes' if guard_ok else 'NO'}",
f"default ARCH works: {'yes' if default_ok else 'no'}",
]
hint = "" if guard_ok else "\n Hint: add `$(error ARCH must be amd64 or arm64)` guarded by an ifneq filter."
if guard_ok and default_ok:
report.add(PASS, 2, "ARCH 守卫与缺省值", "\n".join(lines + hint.splitlines()))
else:
report.add(FAIL, 2, "ARCH 守卫与缺省值", "\n".join(lines) + hint)
def check_version_output(report: Report, project: Path) -> None:
result = run_make(project, "version")
# Dry run: the echoed `@echo <version>` line IS the would-be output.
out_lines = [ln.lstrip()[5:] for ln in result.stdout.splitlines() if ln.lstrip().startswith("echo ")]
out = "\n".join(out_lines).strip()
single = len(out.splitlines()) == 1 and out != ""
no_v = single and not out.startswith("v")
detail = f"stdout={out!r}"
if single and not no_v:
detail += "\ncanonical version must not start with 'v'"
report.add(
PASS if no_v else FAIL,
3,
"version 输出一行非空规范版本(无 v 前缀)",
detail,
)
def check_build_has_no_upload(report: Report, project: Path) -> None:
result = run_make(project, "build")
text = chr(10).join(clean_make_output(result))
hits = [token for token in UPLOAD_TOKENS if token in text]
report.add(
PASS if not hits else FAIL,
4,
"build 不含上传动作",
"clean" if not hits else "found upload commands in build recipe:\n " + ", ".join(hits),
)
def detect_deb_project(recipe_all: str, project: Path) -> bool:
return ".deb" in recipe_all or "dpkg-deb" in recipe_all or "debuild" in recipe_all or any(project.glob("debian/*"))
def check_deb_recipe(report: Report, project: Path, built_deb: Path | None) -> None:
dry = run_make(project, "deb")
text = chr(10).join(clean_make_output(dry))
problems = []
if dry.returncode != 0:
problems.append(f"`make -n deb` failed: {dry.stderr.strip() or 'unknown error'}")
else:
if "dist/" not in text and "$(DIST_DIR)" not in text:
problems.append("recipe does not reference dist/ ($(DIST_DIR)) as artifact location")
hits = [token for token in UPLOAD_TOKENS if token in text]
if hits:
problems.append("recipe contains upload commands: " + ", ".join(hits))
if "rm -rf /" in text or "rm -rf ~" in text:
problems.append("recipe contains unrestricted rm -rf")
if built_deb is not None:
shape_ok = DEB_SHAPE.match(built_deb.name) is not None
if not shape_ok:
problems.append(f"artifact name does not match <name>_<version>_<arch>.deb: {built_deb.name}")
dpkg = shutil.which("dpkg-deb")
if dpkg:
info = subprocess.run([dpkg, "--field", str(built_deb), "Package"], capture_output=True, text=True, check=False)
if info.returncode != 0 or not info.stdout.strip():
problems.append(f"dpkg-deb --info failed on {built_deb.name}")
else:
problems.append("dpkg-deb unavailable; metadata not verified (--build)")
if problems:
report.add(FAIL, 5, "deb 目标产物形状与纯构建", "\n".join(problems))
else:
extra = f"\nartifact: {built_deb.name}" if built_deb else "\n(static recipe check only; run --build to verify real artifact)"
report.add(PASS, 5, "deb 目标产物形状与纯构建", extra.lstrip("\n"))
def detect_docker_project(project: Path) -> bool:
return (project / "Dockerfile").exists() or (project / "docker-compose.yaml").exists()
def check_docker_recipe(report: Report, project: Path) -> None:
dry = run_make(project, "docker")
text = chr(10).join(clean_make_output(dry))
if has_no_rule(dry):
report.add(SKIP, 6, "docker 目标为本地单平台构建", "(no docker target)")
return
problems = []
if "--push" in text or " docker push" in text or "docker push\n" in text:
problems.append("make docker must be local-only; pushing belongs to publish_docker.sh")
if "--platform" in text and "," in text.split("--platform")[1][:80].split()[0]:
problems.append("make docker must stay single-platform; multi-platform belongs to publish_docker.sh")
report.add(FAIL if problems else PASS, 6, "docker 目标为本地单平台构建", "\n".join(problems) or "local single-platform build")
SCRIPT_RESOLVE_SNIPPETS = tuple(
f"{prefix}{name}"
for prefix in (
"$$BUILDER_SKILL_DIR",
"$BUILDER_SKILL_DIR",
"$$HOME/.pouch/skills/builder/scripts",
"$HOME/.pouch/skills/builder/scripts",
"~/.pouch/skills/builder/scripts",
"$$HOME/.skills/skills/builder/scripts",
"$HOME/.skills/skills/builder/scripts",
"~/.skills/skills/builder/scripts",
)
for name in VALID_SCRIPT_NAMES
)
def check_push_delegates(report: Report, project: Path, dual_artifact: bool) -> None:
targets = ("push-deb", "push-docker") if dual_artifact else ("push",)
missing = []
inline = []
thin = []
for target in targets:
dry = run_make(project, target)
if has_no_rule(dry):
missing.append(target)
continue
text = chr(10).join(clean_make_output(dry))
bad_tokens = [token for token in ("curl ", "scp ", "aptly ", "reprepro ") if token in text]
if bad_tokens:
inline.append(f"{target}: inline upload command ({', '.join(bad_tokens)})")
elif not any(snippet in text for snippet in SCRIPT_RESOLVE_SNIPPETS) \
and "$(BUILDER_SCRIPT)" not in text and "upload_deb.sh" not in text \
and "publish_docker.sh" not in text:
inline.append(f"{target}: does not call a builder script (expected $BUILDER_SKILL_DIR/... or ~/.pouch/... path)")
else:
thin.append(target)
problems = []
if missing:
problems.append("missing targets: " + ", ".join(missing))
problems.extend(inline)
status = PASS if not problems else FAIL
detail = "\n".join(problems) if problems else "thin wrappers: " + ", ".join(thin)
report.add(status, 7, "push 仅委托 builder 脚本(薄包装)", detail)
def check_secrets_and_tags(report: Report, project: Path) -> None:
makefile = project / BUILDER_MAKEFILE
problems = []
files = [makefile]
if makefile.exists():
for match in re.finditer(r"^include\s+(.+)$", makefile.read_text(encoding="utf-8"), re.MULTILINE):
inc = (project / match.group(1).strip()).resolve()
if inc.is_file():
files.append(inc)
for file in files:
text = file.read_text(encoding="utf-8")
rel = file.relative_to(project) if file.is_relative_to(project) else file
for pattern in SECRET_PATTERNS:
for hit in pattern.finditer(text):
problems.append(f"{rel}: possible hardcoded secret near `{hit.group(0)[:40]}...`")
for tag in FLOATING_TAGS:
for line in text.splitlines():
stripped = line.split("#", 1)[0]
if tag in stripped:
problems.append(f"{rel}: implicit floating tag `{tag}` in: {stripped.strip()[:70]}")
report.add(FAIL if problems else PASS, 8, "无内联机密、无隐式 latest/stable", "\n".join(problems) or "clean")
DEB_ENV_KEYS = ("DEB_SERVER_URL", "DEB_TOKEN", "DEB_REPOSITORY")
DOCKER_ENV_KEYS = ("DOCKER_REGISTRY",)
ENV_KEY_LINE = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=")
def env_file_keys(project: Path) -> set[str]:
"""Return key names defined in project `.env`. Never return or print values."""
path = project / ".env"
keys: set[str] = set()
if not path.is_file():
return keys
try:
text = path.read_text(encoding="utf-8")
except OSError:
return keys
for raw in text.splitlines():
stripped = raw.strip()
if not stripped or stripped.startswith("#"):
continue
match = ENV_KEY_LINE.match(stripped)
if match:
keys.add(match.group(1))
return keys
def key_present(key: str, env_keys: set[str]) -> bool:
return bool(os.environ.get(key)) or key in env_keys
def check_ready_toolchain(
report: Report, *, deb_project: bool, docker_project: bool
) -> None:
lines = [f"make: {'found' if shutil.which('make') else 'MISSING'}"]
problems = []
if docker_project:
docker_ok = shutil.which("docker") is not None
lines.append(f"docker: {'found' if docker_ok else 'MISSING (blocks docker track)'}")
if not docker_ok:
problems.append("install docker to build/publish images")
else:
lines.append("docker: skipped (no docker track)")
if deb_project:
dpkg_ok = shutil.which("dpkg-deb") is not None
lines.append(
f"dpkg-deb: {'found' if dpkg_ok else 'MISSING (blocks make deb / --build)'}"
)
if not dpkg_ok:
problems.append("install dpkg-dev (or equivalent) to build .deb packages")
else:
lines.append("dpkg-deb: skipped (no deb track)")
report.add(
FAIL if problems else PASS,
10,
"轨道工具链",
"\n".join(lines + ([""] + problems if problems else [])),
)
def check_ready_env_keys(
report: Report, project: Path, *, deb_project: bool, docker_project: bool
) -> None:
env_keys = env_file_keys(project)
lines = []
missing: list[str] = []
if not deb_project and not docker_project:
report.add(SKIP, 11, "发布环境变量键名(不读取值)", "no deb/docker track")
return
if deb_project:
for key in DEB_ENV_KEYS:
found = key_present(key, env_keys)
lines.append(f"{key}: {'present' if found else 'MISSING'}")
if not found:
missing.append(key)
else:
lines.append("DEB_*: skipped (no deb track)")
if docker_project:
for key in DOCKER_ENV_KEYS:
found = key_present(key, env_keys)
lines.append(f"{key}: {'present' if found else 'MISSING'}")
if not found:
missing.append(key)
else:
lines.append("DOCKER_*: skipped (no docker track)")
if missing:
lines.extend(
[
"",
"blocks publish, not build. Put keys in the environment or project `.env`:",
*[f" {key}=" for key in missing],
"Do not commit `.env`. Never print values.",
]
)
report.add(SKIP, 11, "发布环境变量键名(不读取值)", "\n".join(lines))
return
report.add(PASS, 11, "发布环境变量键名(不读取值)", "\n".join(lines))
def check_script_paths(report: Report) -> None:
candidates = []
env_dir = os.environ.get("BUILDER_SKILL_DIR")
if env_dir:
candidates.append(Path(env_dir) / "scripts")
home = Path(os.environ.get("HOME", ""))
candidates.append(home / ".pouch" / "skills" / "builder" / "scripts")
candidates.append(home / ".skills" / "skills" / "builder" / "scripts")
found = next((c for c in candidates if c.is_dir() and any((c / n).is_file() for n in VALID_SCRIPT_NAMES)), None)
if found:
report.add(PASS, 9, "builder 脚本路径可达", str(found))
else:
report.add(FAIL, 9, "builder 脚本路径可达", "\n".join([
"none of these resolve to scripts/upload_deb.sh:",
*(f" {c}" for c in candidates),
"Fix: set BUILDER_SKILL_DIR, or clone the pouch repo to ~/.pouch.",
]))
def build_project(project: Path) -> Path | None:
"""Run `make -f makefile.builder deb` for real and return the produced .deb, or None."""
result = run_make(project, "deb", timeout=1800, dry_run=False)
if result.returncode != 0:
print(
f"--build: `make -f {BUILDER_MAKEFILE} deb` failed:\n{result.stderr[-2000:]}",
file=sys.stderr,
)
return None
debs = sorted((p for p in (project / "dist").glob("*.deb") if p.is_file()), key=lambda p: p.stat().st_mtime, reverse=True)
return debs[0] if debs else None
MAKEFILE_HINT = (
f"Fix: copy <builder-skill>/templates/{BUILDER_MAKEFILE} to the project "
f"root as {BUILDER_MAKEFILE}. Do not put builder targets in Makefile or "
"makefile. Keep help/build/clean/version, include builder "
"scripts/version.mk, and enable deb/docker/push* for the tracks this "
"project actually uses. Then re-run check.py. Do not use create-makefile."
)
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument(
"project",
type=Path,
help="project directory containing makefile.builder",
)
parser.add_argument(
"--build",
action="store_true",
help="actually run `make -f makefile.builder deb` and verify the artifact",
)
parser.add_argument(
"--ready",
action="store_true",
help="also check toolchain and publish env key names (init/check mode)",
)
args = parser.parse_args(argv)
project = args.project.resolve()
makefile = project / BUILDER_MAKEFILE
if not makefile.is_file():
if not args.ready:
print(f"Error: no {BUILDER_MAKEFILE} in {project}", file=sys.stderr)
return 2
report = Report()
report.add(
FAIL,
1,
f"{BUILDER_MAKEFILE} 存在",
f"no {BUILDER_MAKEFILE} in {project}\n{MAKEFILE_HINT}",
)
skip_detail = f"(no {BUILDER_MAKEFILE})"
for number, title, detail in (
(2, "ARCH 守卫与缺省值", skip_detail),
(3, "version 输出一行非空规范版本(无 v 前缀)", skip_detail),
(4, "build 不含上传动作", skip_detail),
(5, "deb 目标产物形状与纯构建", skip_detail),
(6, "docker 目标为本地单平台构建", skip_detail),
(7, "push 仅委托 builder 脚本(薄包装)", skip_detail),
(8, "无内联机密、无隐式 latest/stable", skip_detail),
(9, "builder 脚本路径可达", skip_detail),
):
report.add(SKIP, number, title, detail)
docker_project = detect_docker_project(project)
deb_project = any(project.glob("debian/*"))
check_ready_toolchain(report, deb_project=deb_project, docker_project=docker_project)
check_ready_env_keys(
report, project, deb_project=deb_project, docker_project=docker_project
)
print()
print(f"RESULT: FAILED ({report.failures} check(s) failed)")
return 1
if shutil.which("make") is None:
print("Error: make is required.", file=sys.stderr)
return 2
report = Report()
# Gather every recipe once via dry-running all known targets (best effort).
recipe_all_parts = []
for target in (*REQUIRED_TARGETS, "deb", "docker", "push", "push-deb", "push-docker"):
result = run_make(project, target)
if result.returncode == 0:
recipe_all_parts.append(result.stdout)
recipe_all = "\n".join(recipe_all_parts)
present = check_required_targets(report, project)
built_deb: Path | None = None
deb_project = detect_deb_project(recipe_all, project)
docker_project = detect_docker_project(project)
if present["build"]:
check_arch_guard(report, project)
check_version_output(report, project)
check_build_has_no_upload(report, project)
else:
report.add(SKIP, 2, "ARCH 守卫与缺省值", "(build target missing)")
report.add(SKIP, 3, "version 输出一行非空规范版本(无 v 前缀)", "(version target missing)")
report.add(SKIP, 4, "build 不含上传动作", "(build target missing)")
if deb_project:
if args.build:
print(f"--build: running `make -f {BUILDER_MAKEFILE} deb` ...")
built_deb = build_project(project)
if built_deb is None:
print("--build: no .deb produced; artifact checks degrade to recipe-only.", file=sys.stderr)
check_deb_recipe(report, project, built_deb)
else:
report.add(SKIP, 5, "deb 目标产物形状与纯构建", "(not a DEB project)")
if docker_project:
check_docker_recipe(report, project)
else:
report.add(SKIP, 6, "docker 目标为本地单平台构建", "(no Dockerfile)")
dual = deb_project and docker_project
check_push_delegates(report, project, dual)
check_secrets_and_tags(report, project)
check_script_paths(report)
if args.ready:
check_ready_toolchain(
report, deb_project=deb_project, docker_project=docker_project
)
check_ready_env_keys(
report, project, deb_project=deb_project, docker_project=docker_project
)
total_fail = report.failures
print()
if total_fail:
print(f"RESULT: FAILED ({total_fail} check(s) failed)")
return 1
print("RESULT: PASSED")
return 0
if __name__ == "__main__":
raise SystemExit(main())