From 681aa9e237f6b8a728b0d5387b8de4fb1863cfe3 Mon Sep 17 00:00:00 2001 From: laily Date: Tue, 25 Aug 2026 16:58:56 +0800 Subject: [PATCH] feat(builder): load publish credentials from .env.builder Keep DEB/Docker publish keys out of the project's .env. Scripts and check.py --ready only read .env.builder; empty values count as missing. --- skills/_template/SKILL.md | 4 +-- skills/builder/README.md | 7 +++-- skills/builder/SKILL.md | 27 ++++++++-------- skills/builder/references/contract.md | 13 +++++--- skills/builder/references/registry.md | 2 +- skills/builder/scripts/check.py | 16 ++++++---- skills/builder/scripts/publish_docker.sh | 15 ++++----- skills/builder/scripts/upload_deb.sh | 19 ++++++------ skills/builder/templates/env.builder | 13 ++++++++ tests/test_builder_check.py | 39 +++++++++++++++++++++++- 10 files changed, 109 insertions(+), 46 deletions(-) create mode 100644 skills/builder/templates/env.builder diff --git a/skills/_template/SKILL.md b/skills/_template/SKILL.md index eefdb87..8ab27d7 100644 --- a/skills/_template/SKILL.md +++ b/skills/_template/SKILL.md @@ -49,8 +49,8 @@ description: >- 项目状态放在 skill 真正消费的位置（覆盖层、`makefile.builder`、compose），不要为了对齐 而新建一层没人读的 `.pouch//`。`pouch init` 只用于确实有 templates/ -覆盖层的 skill。需要 make 目标的 skill 用自己的文件名（如 `makefile.builder`）， -不要占用用户的 `Makefile`。 +覆盖层的 skill。需要 make 目标或发布凭据的 skill 用自己的文件名（如 `makefile.builder`、 +`.env.builder`），不要占用用户的 `Makefile` 或 `.env`。 --- diff --git a/skills/builder/README.md b/skills/builder/README.md index b41f19c..dc6241e 100644 --- a/skills/builder/README.md +++ b/skills/builder/README.md @@ -18,19 +18,19 @@ 对新项目说「用 builder 初始化」。Agent 会探测轨道、按 `templates/makefile.builder` 写出项目根 `makefile.builder`，并列出缺的发布配置。 -不改用户已有的 `Makefile`。 +不改用户已有的 `Makefile` 或 `.env`。 1. `makefile.builder` 目标：`help/build/clean/version` + 条件 `deb/docker/push*`， 变量 `ARCH/VERSION/DIST_DIR/PROJECT_NAME`。 `VERSION` 通过 `include /scripts/version.mk` 从 Git 推导。 2. 运行 `python3 -I -S /scripts/check.py . --ready` 直到构建项 PASS。 缺发布键只挡住上传，不挡住构建。 -3. 在项目根 `.env` 配置发布环境变量： +3. 在项目根 `.env.builder` 配置发布环境变量（不要写进 `.env`）： ```text DEB_SERVER_URL=https://deb.example.com DEB_REPOSITORY=main -DEB_TOKEN= # 只放 .env 或密钥系统，不进 git +DEB_TOKEN= # 只放 .env.builder 或密钥系统，不进 git DOCKER_REGISTRY=registry.example.com ``` @@ -104,6 +104,7 @@ detached HEAD 用 `detached`，CI 可注入 `BUILD_BRANCH` / `CI_COMMIT_BRANCH` |------|------| | `scripts/check.py` | 校验契约（`--ready` 含工具链与发布键名，`--build` 实构核对产物） | | `templates/makefile.builder` | 初始化用的契约文件骨架，拷到项目根 | +| `templates/env.builder` | 初始化用的 `.env.builder` 骨架（注释键，不含值） | | `scripts/version.sh` | 从 Git 祖先稳定 tag 推导规范版本 / Docker tag | | `scripts/version.mk` | `makefile.builder` `include`，设置 `VERSION` 与 `IMAGE_TAG` | | `scripts/upload_deb.sh` | 上传 `.deb` 到 HTTP 包仓库（multipart package/token/repository_name） | diff --git a/skills/builder/SKILL.md b/skills/builder/SKILL.md index a63cd5a..740b1bd 100644 --- a/skills/builder/SKILL.md +++ b/skills/builder/SKILL.md @@ -15,8 +15,8 @@ description: >- 复用项目已有发布约定，安全地完成"校验 → 构建 → 检查 → 授权 → 上传 → 验证"。 分工原则：**make 管构建，skill 脚本管发布，本 SKILL.md 只留脚本做不了的决策。** -项目状态是根目录 `makefile.builder` 与发布用 `.env`，不要创建 `.pouch/builder/`， -不要改用户的 `Makefile` / `makefile`。 +项目状态是根目录 `makefile.builder` 与发布用 `.env.builder`，不要创建 +`.pouch/builder/`，不要改用户的 `Makefile` / `makefile` / `.env`。 开始时解析当前 `SKILL.md` 所在目录，记为 ``。优先 `git rev-parse --show-toplevel` 解析项目根。 @@ -39,9 +39,9 @@ description: >- ## 初始化 -1. 确认项目根。探测 `makefile.builder`、用户 `Makefile`/`makefile`（只当证据， - 不改）、`Dockerfile`、`debian/`、语言清单、`.env` 键名（只看键是否存在，不读、 - 不打印值）。 +1. 确认项目根。探测 `makefile.builder`、`.env.builder`、用户 `Makefile`/`makefile` + （只当抄 build 配方的证据，不改）、`Dockerfile`、`debian/`、语言清单。 + `.env.builder` 只看键是否存在且非空，不读、不打印值。不要读取用户 `.env`。 2. 判定轨道：有 Dockerfile → docker；有 deb 信号或用户要打 deb → deb；都不清则问。 不要猜测 registry、token 或仓库名。 3. 没有 `makefile.builder`：把 `/templates/makefile.builder` 拷到项目根。 @@ -51,7 +51,9 @@ description: >- `push: push-deb push-docker`。不要改用户的 `Makefile` / `makefile`。 4. 已有 `makefile.builder`：跑检查；按 FAIL 给出修补说明。不覆盖该文件，除非 用户明确要求按契约改。不要调用 create-makefile（其版本规则与本契约冲突）。 -5. 不要创建 `.env`。缺发布键时在报告里给出可粘贴示例，并说明 `.env` 不进 Git。 +5. 没有 `.env.builder`：把 `/templates/env.builder` 拷到项目根为 + `.env.builder`（注释键，不含值）。不要改、不要读取用户 `.env`。缺发布键时在 + 报告里给出可粘贴示例，并说明把 `.env.builder` 加入 `.gitignore`，不要提交。 6. 运行： ```bash @@ -74,6 +76,7 @@ description: >- 发布键示例（只示范键名）： ```text +# .env.builder DEB_SERVER_URL=https://deb.example.com DEB_REPOSITORY=main DEB_TOKEN= @@ -83,8 +86,8 @@ DOCKER_REGISTRY=registry.example.com ## 检查 只读。运行 `check.py --ready`，用同一报告格式，标题改为 -`## builder 检查：…`。不写 `makefile.builder`、不改用户 Makefile、不创建 `.env`。 -用户明确要求修复后再转入初始化。 +`## builder 检查：…`。不写 `makefile.builder` / `.env.builder`，不改用户 Makefile +或 `.env`。用户明确要求修复后再转入初始化。 ## 工作流 @@ -108,7 +111,7 @@ python3 -I -S /scripts/check.py --build # 额外实构 执行上传前确认： -- 目标服务和仓库来自项目配置（`.env`）或用户输入，不猜测生产端点。 +- 目标服务和仓库来自项目配置（`.env.builder`）或用户输入，不猜测生产端点。 - 认证令牌已通过环境变量或密钥系统提供；绝不写入命令输出、文件、提交或回复， 不用 `set -x` 执行含凭据的命令。 - 相同版本是否允许覆盖；无法确认且可能覆盖时，先询问。 @@ -152,7 +155,7 @@ DOCKER_REGISTRY=… \ /scripts/publish_docker.sh # env 优先，flag 可覆盖 ``` -环境变量缺失时脚本会自动向上查找项目 `.env` 加载（shell 显式值优先）。不把 token +环境变量缺失时脚本会加载项目 `.env.builder`（shell 显式值优先），不读 `.env`。不把 token 作为命令行参数；不把脚本复制进项目。upload_deb.sh 默认请求 `/api/v2/upload/package` （multipart 字段 `package`/`token`/`repository_name`，接受 200/201），协议不符时设 `DEB_UPLOAD_PATH` 或改用项目专属逻辑。publish_docker.sh 用 buildx 一步完成构建+推送， @@ -188,8 +191,8 @@ rg -n -i --hidden --glob '!.git' \ - 上传/发布脚本是 SSOT：通用行为修改落在 `skills/builder/scripts/`，不同步复制到 业务项目。产物版本只通过 `scripts/version.sh` 推导，不要在 `makefile.builder` 内联 `git describe` 或 `sort -V`。 -- 契约变更先改 `scripts/check.py`，再同步 `references/contract.md` 与 - `templates/makefile.builder`。 +- 契约变更先改 `scripts/check.py`，再同步 `references/contract.md`、 + `templates/makefile.builder` 与 `templates/env.builder`。 - 可用 `bash -n` 检查脚本语法；有 ShellCheck 时一并运行。 - 不通过真实生产上传测试脚本，除非用户明确授权并给出测试版本/仓库。 diff --git a/skills/builder/references/contract.md b/skills/builder/references/contract.md index 4d38efb..af93297 100644 --- a/skills/builder/references/contract.md +++ b/skills/builder/references/contract.md @@ -16,6 +16,9 @@ make -f makefile.builder 不要把 builder 目标写进用户的 `Makefile` 或 `makefile`。`check.py` 只读 `makefile.builder`。 +发布凭据固定为项目根 `.env.builder`。不要把这些键写进用户的 `.env`。脚本不读取 +`.env`。 + ## 1. Make 目标 ### 必备目标（所有项目） @@ -113,9 +116,9 @@ include $(HOME)/.pouch/skills/builder/scripts/version.mk | `IMAGE_TAG` | 否 | 默认由规范版本渲染：正式为 `X.Y.Z`；测试将 `~` 换成 `-`、`+g` 换成 `.g` | | `PLATFORMS` | 否 | 默认 `linux/amd64`；多平台如 `linux/amd64,linux/arm64` | -配置来源优先级：shell 已显式设置的值 > 项目根 `.env` > 失败并询问用户。 -`.env` 由 builder 脚本自动向上查找并加载（不回显任何值）；当前 shell 已设置的值 -优先于 `.env`。 +配置来源优先级：shell 已显式设置的值 > 项目根 `.env.builder` > 失败并询问用户。 +`.env.builder` 由 builder 脚本加载（不回显任何值）；当前 shell 已设置的值优先。 +不要读取或改写用户 `.env`。空值视为未配置。不要提交 `.env.builder`。 ### 工作区安全 @@ -137,8 +140,8 @@ clone 到 `~/.pouch`。 `python3 -I -S /check.py [--build]` 对本项目逐条检查 上述要求，任一 FAIL 退出码非零，可直接挂 CI。`--build` 额外实构 `make -f makefile.builder deb` 并核对产物元数据（默认只静态检查配方）。`--ready` -额外检查轨道工具链，以及 `.env` / 环境中的发布键名是否存在（不读取、不打印值； -缺键只挡住发布）。校验失败时的修复路径：按 `templates/makefile.builder` 补齐或 +额外检查轨道工具链，以及 `.env.builder` / 环境中的发布键名是否存在且非空（不读取、 +不打印值；缺键只挡住发布）。校验失败时的修复路径：按 `templates/makefile.builder` 补齐或 修正 `makefile.builder`，再跑 check.py，不要绕过校验器，不要改用户 Makefile， 不要用 create-makefile（版本推导与本契约冲突）。 diff --git a/skills/builder/references/registry.md b/skills/builder/references/registry.md index de50509..8c48701 100644 --- a/skills/builder/references/registry.md +++ b/skills/builder/references/registry.md @@ -14,7 +14,7 @@ 信息来源优先级： 1. 用户本次请求中明确给出的值。 -2. 当前项目的 `.env` 与 `AGENTS.md`、发布文档。 +2. 当前项目的 `.env.builder` 与 `AGENTS.md`、发布文档。不要读用户 `.env`。 3. `makefile.builder`、用户 Makefile、CI 配置或现有构建脚本中一致且无歧义的配置。 4. 询问用户。 diff --git a/skills/builder/scripts/check.py b/skills/builder/scripts/check.py index 44b514d..8644cb0 100755 --- a/skills/builder/scripts/check.py +++ b/skills/builder/scripts/check.py @@ -43,6 +43,7 @@ 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" +BUILDER_ENV = ".env.builder" PASS = "PASS" FAIL = "FAIL" @@ -279,12 +280,12 @@ def check_secrets_and_tags(report: Report, project: Path) -> None: 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_]*)=") +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" + """Return nonempty key names in `.env.builder`. Never return or print values.""" + path = project / BUILDER_ENV keys: set[str] = set() if not path.is_file(): return keys @@ -297,7 +298,10 @@ def env_file_keys(project: Path) -> set[str]: if not stripped or stripped.startswith("#"): continue match = ENV_KEY_LINE.match(stripped) - if match: + if not match: + continue + value = match.group(2).strip().strip("'\"") + if value: keys.add(match.group(1)) return keys @@ -364,9 +368,9 @@ def check_ready_env_keys( lines.extend( [ "", - "blocks publish, not build. Put keys in the environment or project `.env`:", + f"blocks publish, not build. Put keys in the environment or {BUILDER_ENV}:", *[f" {key}=" for key in missing], - "Do not commit `.env`. Never print values.", + f"Do not commit {BUILDER_ENV}. Do not put these keys in `.env`. Never print values.", ] ) report.add(SKIP, 11, "发布环境变量键名（不读取值）", "\n".join(lines)) diff --git a/skills/builder/scripts/publish_docker.sh b/skills/builder/scripts/publish_docker.sh index e50627c..018db63 100755 --- a/skills/builder/scripts/publish_docker.sh +++ b/skills/builder/scripts/publish_docker.sh @@ -6,8 +6,8 @@ usage() { } # Build and publish a Docker image with buildx. Configuration comes from the -# environment first (optionally loaded from the project root .env); flags -# override. +# environment first (optionally loaded from the project root .env.builder); +# flags override. Does not read `.env`. # # Usage: # publish_docker.sh [--registry HOST] [--repository PATH] [--tag TAG] \ @@ -30,18 +30,19 @@ usage() { project_root=$(git rev-parse --show-toplevel 2>/dev/null || true) -# Load project .env without printing values; explicitly exported shell values keep precedence. -if [[ -n "$project_root" && -f "$project_root/.env" ]]; then +# Load .env.builder without printing values; shell values win. Do not read `.env`. +if [[ -n "$project_root" && -f "$project_root/.env.builder" ]]; then while IFS='=' read -r key value; do key=${key%%[[:space:]]*} [[ -z "$key" || "$key" == \#* ]] && continue if [[ -n "${!key:-}" ]]; then - continue # shell value already set: wins over .env + continue # shell value already set: wins over .env.builder fi value=${value%\"}; value=${value#\"}; value=${value%\'}; value=${value#\'} + [[ -z "$value" ]] && continue printf -v "$key" '%s' "$value" export "$key" - done < <(grep -v '^[[:space:]]*$' "$project_root/.env") + done < <(grep -v '^[[:space:]]*$' "$project_root/.env.builder") fi git_repo_name= @@ -81,7 +82,7 @@ if [[ -n "$registry" && ( "$registry" == *://* || "$registry" == */* ) ]]; then fi if [[ -z "$registry" ]]; then echo "Error: DOCKER_REGISTRY (or --registry) is required." >&2 - echo "Set it in the environment or the project root .env." >&2 + echo "Set it in the environment or the project root .env.builder." >&2 usage >&2 exit 2 fi diff --git a/skills/builder/scripts/upload_deb.sh b/skills/builder/scripts/upload_deb.sh index aadba0a..41f245a 100755 --- a/skills/builder/scripts/upload_deb.sh +++ b/skills/builder/scripts/upload_deb.sh @@ -15,9 +15,9 @@ Options: -p UPLOAD_PATH Override DEB_UPLOAD_PATH (default: /api/v2/upload/package) -h Show help -Environment variables may live in the project root .env; this script walks up -from the current directory, loads it silently (existing shell values win), and -never echoes variable values. The endpoint must accept multipart fields named +Environment variables may live in the project root .env.builder; this script +loads it silently (existing shell values win), never echoes values, and does +not read `.env`. The endpoint must accept multipart fields named package, token, and repository_name. Authentication is read only from DEB_TOKEN so it is not exposed in the process command line. @@ -25,21 +25,22 @@ The working tree must be clean to publish; set ALLOW_UNCOMMITTED=1 to override. EOF } -# Locate project root (.git) upward from cwd for .env loading and git checks. +# Locate project root (.git) upward from cwd for .env.builder loading and git checks. project_root=$(git rev-parse --show-toplevel 2>/dev/null || true) -# Load project .env without printing values; explicitly exported shell values keep precedence. -if [[ -n "$project_root" && -f "$project_root/.env" ]]; then +# Load .env.builder without printing values; shell values win. Do not read `.env`. +if [[ -n "$project_root" && -f "$project_root/.env.builder" ]]; then while IFS='=' read -r key value; do key=${key%%[[:space:]]*} [[ -z "$key" || "$key" == \#* ]] && continue if [[ -n "${!key:-}" ]]; then - continue # shell value already set: wins over .env + continue # shell value already set: wins over .env.builder fi value=${value%\"}; value=${value#\"}; value=${value%\'}; value=${value#\'} + [[ -z "$value" ]] && continue printf -v "$key" '%s' "$value" export "$key" - done < <(grep -v '^[[:space:]]*$' "$project_root/.env") + done < <(grep -v '^[[:space:]]*$' "$project_root/.env.builder") fi server_url=${DEB_SERVER_URL:-} @@ -61,7 +62,7 @@ shift $((OPTIND - 1)) if [[ -z "$server_url" || -z "$repository" || -z "$token" || $# -eq 0 ]]; then echo "Error: DEB_SERVER_URL, DEB_TOKEN, DEB_REPOSITORY, and at least one file are required." >&2 - echo "Set them in the environment or the project root .env." >&2 + echo "Set them in the environment or the project root .env.builder." >&2 usage >&2 exit 2 fi diff --git a/skills/builder/templates/env.builder b/skills/builder/templates/env.builder new file mode 100644 index 0000000..2c4d641 --- /dev/null +++ b/skills/builder/templates/env.builder @@ -0,0 +1,13 @@ +# Builder publish credentials. Copy to the project root as `.env.builder`. +# Do not commit this file. Do not put these keys in the project's `.env`. +# Uncomment and fill the keys for tracks this project uses. +# Shell-exported values override this file. +# +# DEB_SERVER_URL= +# DEB_TOKEN= +# DEB_REPOSITORY= +# DEB_UPLOAD_PATH= +# DOCKER_REGISTRY= +# DOCKER_REPOSITORY= +# IMAGE_TAG= +# PLATFORMS= diff --git a/tests/test_builder_check.py b/tests/test_builder_check.py index a2c4111..74506c2 100644 --- a/tests/test_builder_check.py +++ b/tests/test_builder_check.py @@ -95,10 +95,13 @@ class BuilderCheckTests(unittest.TestCase): self.assertIn("check.py", skill) self.assertIn("--ready", skill) self.assertIn("makefile.builder", skill) + self.assertIn(".env.builder", skill) self.assertIn("不要改用户的 `Makefile`", skill) self.assertIn("不要调用 create-makefile", skill) self.assertIn("不要用 create-makefile", contract) self.assertIn("makefile.builder", contract) + self.assertIn(".env.builder", contract) + self.assertIn("不要读取或改写用户 `.env`", contract) def test_no_makefile_without_ready_is_usage_error(self) -> None: with tempfile.TemporaryDirectory() as temp: @@ -136,7 +139,7 @@ class BuilderCheckTests(unittest.TestCase): project = Path(temp) init_repo(project) write_contract_makefile(project) - (project / ".env").write_text( + (project / ".env.builder").write_text( "DEB_SERVER_URL=https://secret.example.com\n" "DEB_TOKEN=super-secret-token-value\n" "DEB_REPOSITORY=main\n", @@ -151,6 +154,40 @@ class BuilderCheckTests(unittest.TestCase): self.assertNotIn("super-secret-token-value", text) self.assertNotIn("https://secret.example.com", text) + def test_user_dotenv_is_ignored(self) -> None: + with tempfile.TemporaryDirectory() as temp: + project = Path(temp) + init_repo(project) + write_contract_makefile(project) + (project / ".env").write_text( + "DEB_SERVER_URL=https://user.example.com\n" + "DEB_TOKEN=user-env-secret-token\n" + "DEB_REPOSITORY=main\n", + encoding="utf-8", + ) + code, text = run_check( + project, "--ready", which={"dpkg-deb": "/usr/bin/dpkg-deb"} + ) + self.assertEqual(code, 0, text) + self.assertIn("DEB_SERVER_URL: MISSING", text) + self.assertNotIn("user-env-secret-token", text) + self.assertNotIn("https://user.example.com", text) + + def test_empty_env_builder_values_count_as_missing(self) -> None: + with tempfile.TemporaryDirectory() as temp: + project = Path(temp) + init_repo(project) + write_contract_makefile(project) + (project / ".env.builder").write_text( + "DEB_SERVER_URL=\nDEB_TOKEN=\nDEB_REPOSITORY=\n", + encoding="utf-8", + ) + code, text = run_check( + project, "--ready", which={"dpkg-deb": "/usr/bin/dpkg-deb"} + ) + self.assertEqual(code, 0, text) + self.assertIn("DEB_TOKEN: MISSING", text) + def test_ready_fails_when_docker_track_missing_docker(self) -> None: with tempfile.TemporaryDirectory() as temp: project = Path(temp)