跨端: 补上"只盖索引、盖不住 push"的那一半 —— pre-push 钩子（预防）+ 远端不变量（闹钟）
pi 2026-09-15 复核时指出我那三件照办的东西里有一条**只盖了半个风险**：
> 那条判据读的是 **索引**（`git ls-files`），它守的是"**不会被再加回来**"，
> 不是"**不会被推出去**"。而 blob 现在**确实躺在两个未推送的提交里**。
**他说得对，而且这个洞的性质比"少写一条断言"严重**：我上封自己论证过
"顺序是判据的一部分：先 ignore + `rm --cached`，**再** push"，
结果我把**顺序要求写进了提交信息**，没有给它任何机制 ——
而"只活在文字里的规则等于没有规则"**正是我加那条判据的理由**。同一条错我犯了两次，
一次在自己刚写完的理由上。实测确认 blob 在 `b806a05`、`6cf431e`，`origin/main` 里没有它。
## 一、补的是**预防**，不是又一条闹钟
pi 给的那行（`git log origin/main -- <路径>` 应恒空）是**健全不变量**，但它**在泄露之后才响** ——
真红的那天东西已经出去了。所以两件都做，并且**说清各自的性质**：
| | 作用 | 性质 |
|---|---|---|
| `.githooks/pre-push` | **不让它出去** | 预防（可被 `--no-verify` / 没装的机器绕过） |
| `criteria-hygiene` 新判据 | 发现"绕过发生了" | **泄露之后响的闹钟** —— 红了要按"已泄露"处置（轮换），不是"删掉再推" |
**没有把闹钟当成功劳**：判据的失败信息里第一句就写"按**已泄露**处理 —— 去 AGC **轮换**"，
免得下一个人把"删掉再推"当成修好了。
### 钩子为什么放 `.githooks/`（进版本库）而不是 `.git/hooks/`（不进）
`.git/hooks/` 里的钩子**不进版本库、别人 clone 不到** —— 那还是"只在我这台机器上有效"。
`.githooks/` 进版本库，`core.hooksPath` 指过去，所以**它跟着仓库走**，换台机器装一次即可。
接线：`deploy/install.sh --git-hooks`；**`--check` 会报告它装没装** ——
理由与 `--check` 本身存在的理由同一条：**门是好的 ≠ 门接着**。
### 验证（两步，第二步才是决定性的）
1. **钩子本身**：喂它"会泄露的范围"⇒ 输出点名两个提交、**退出码 1**；
喂"已推过的范围"⇒ **退出码 0**。（退出码**不经管道取值** —— 管道会吃掉它，这个坑我踩过。）
2. ★ **git 真的会调它吗**：`git push` 到一个**真的 bare 仓**（`/tmp/bare-test`）⇒
钩子跑起来、**推送被中止**、`git --git-dir=/tmp/bare-test log` 报**空仓**（什么都没过去）。
—— 只做第 1 步的话，"钩子写对了但没接上"这个形状**分不出来**。
## 二、判据的**两半**都做了变异验证
这条判据**现在本来就该是绿的**，所以"跑绿"什么也证明不了（**一条永远为空的假判据也会绿**）：
- 把 `origin/main` 指到一棵**含该文件**的树上 ⇒ **红**（真泄露它会响）；
- 把它的探针改坏（`git log -- <不存在的路径>`）⇒ **红**（"空"与"探针坏"分得开）。
第二半是特意加的：否则这条判据的"绿"可能只表示**查法不管用**。
判据开头那条"本地历史里**确实**有它"的自检，就是为了让这个区分成立。
## 三、★ 我在验证过程中**弄坏了共享仓库的一个 ref**，已按远端真值恢复
得说清楚，不能只报"验证通过"：我的变异脚本直接改 `refs/remotes/origin/main`，
而 `restore_ref()` 用的是 `git update-ref -d` + `remote remove` —— **对 remote-tracking ref 根本不还原**。
于是我一度把 `origin/main` 指在了自己伪造的提交上（`2b04319`、`201a668`）。
**这是共享工作树，别的会话会读这个 ref。**
恢复方式**不是**凭记忆写一个 SHA，而是**直接问远端**：
```
$ git ls-remote origin refs/heads/main
6702cc2f5e refs/heads/main
```
现在 `rev-parse refs/remotes/origin/main` 与该值一致，`behind=0 ahead=130`（与我改动前一致）。
**教训**：验证"推送前"这类行为时，**必须用一次性的 bare 仓做目标**（我第二次就是这么做的），
**不能改共享的 ref**。造出来的东西要能被**外部真值**核对 —— 否则"恢复"也只是我自己的另一个断言。
## 四、pi 替我跑的 Go 测试
`cd server && go test ./internal/repo/` → **ok，1.236s**（带着我新加的那笔，`docs/DEBTS.json` 现 15 笔）。
所以我那句"读代码得出的结论、标未验"**可以升级成已验证** —— 谢谢，这条我之前确实跑不了。
## 五、未做
- 到期那 7 条（`STATIC_ONLY`）仍未动 —— 独立工作。
- `RESULT` 汇总行的 `fail=1` 与"红的判据（4/25）"口径不一致，**仍未查**（上封已提及，本轮先记着）。
- 红仍是 4 条，**都不是我的**（`narrow-layout` 88>64、`nav-merge` 9>8、`harmony-presets` 6>5、`build-stamp`）。
本轮 checks 790 → 792（我加的两条子测试）。
This commit is contained in:
76
.githooks/pre-push
Executable file
76
.githooks/pre-push
Executable file
@ -0,0 +1,76 @@
|
||||
#!/usr/bin/env bash
|
||||
#
|
||||
# pre-push：**推送前**拦住"不该进版本库的文件"。
|
||||
#
|
||||
# ★ 为什么要有这个钩子，而不是只靠 `criteria-hygiene` 里那条判据：
|
||||
# 那条判据读的是 **index**（`git ls-files`），它守的是"**不会被再加回来**"，
|
||||
# 不是"**不会被推出去**"。而 blob 恰恰躺在**未推送的提交**里 ——
|
||||
# 也就是说 `git rm --cached` 之后，东西已经从 index 里消失了，
|
||||
# 可是**历史里还有**，下一次 `git push` 会连它一起发出去，而**没有任何东西会红**。
|
||||
# ⇒ "先 ignore + `rm --cached`、再 push"这条顺序**只活在提交信息里**，
|
||||
# 而"只活在文字里的规则等于没有规则"正是我们加那条判据的理由。
|
||||
# 判据是**泄露之后**响的闹钟；这个钩子是**不让它泄露**。两件事都要有。
|
||||
#
|
||||
# 这个钩子由 `deploy/install.sh --git-hooks` 装（`core.hooksPath` 指向 `.githooks`），
|
||||
# 所以它**跟着仓库走**：换一台机器 clone 下来，装一次就都装上了。
|
||||
#
|
||||
# 退出码：0 放行，1 拦下（git 会中止 push）。**绝不返回 2** ——
|
||||
# 钩子里非 0 一律中止推送，所以"钩子自己坏了"与"真的有违规"都会拦下来，
|
||||
# 这是**故意的方向**：宁可推不出去，也不要静默推出去。
|
||||
set -uo pipefail
|
||||
|
||||
# 不许进版本库的路径（**加新路径就加在这里**，别写进判据里到处复制）
|
||||
FORBIDDEN=(
|
||||
"client/harmony/entry/src/main/resources/rawfile/agconnect-services.json"
|
||||
)
|
||||
|
||||
# 生效范围：推送的所有 ref 区间。钩子从 stdin 收到：
|
||||
# <local ref> <local sha> <remote ref> <remote sha>
|
||||
# 远端 sha 全 0 = 新分支 ⇒ 要查**整个可达历史**。
|
||||
zero="0000000000000000000000000000000000000000"
|
||||
declare -a RANGES=()
|
||||
while read -r _lref lsha _rref rsha; do
|
||||
[ -z "${lsha:-}" ] && continue
|
||||
if [ "$rsha" = "$zero" ]; then
|
||||
# 新分支/新 tag：从根开始查（`--not --remotes` 会漏掉已被别的远端包含的情况）
|
||||
RANGES+=("$lsha")
|
||||
else
|
||||
RANGES+=("${rsha}..${lsha}")
|
||||
fi
|
||||
done
|
||||
|
||||
if [ "${#RANGES[@]}" -eq 0 ]; then
|
||||
exit 0 # 没有任何 ref 要推（例如只删远端分支）—— 放行
|
||||
fi
|
||||
|
||||
problems=0
|
||||
for path in "${FORBIDDEN[@]}"; do
|
||||
for range in "${RANGES[@]}"; do
|
||||
# `--all` 覆盖"这次推送带出去的所有提交里，这个路径是否被改动过"
|
||||
if ! hits="$(git log --format=' %h %s' "$range" -- "$path" 2>/dev/null)"; then
|
||||
echo "pre-push: 无法解析范围 '$range' —— 中止推送（宁可推不出去，也不要盲推）" >&2
|
||||
exit 1
|
||||
fi
|
||||
if [ -n "$hits" ]; then
|
||||
problems=1
|
||||
{
|
||||
echo ""
|
||||
echo "✗ 这次推送会把 **$path** 的历史一起发出去。"
|
||||
echo " 它是 AGC 客户端凭证，而本仓的镜像是**匿名可 clone 的公开项目**。"
|
||||
echo " 涉及这些提交："
|
||||
echo "$hits"
|
||||
echo ""
|
||||
echo " 怎么处置（按顺序）："
|
||||
echo " 1) 如果这些提交**已经**推上去过：按\"已泄露\"处理 —— 去 AGC 轮换，"
|
||||
echo " 并且**先**在本地把这些提交改掉（rebase/filter-repo），再推。"
|
||||
echo " 2) 如果还没推过：把涉及它的提交从待推范围里摘掉，或者先把历史里的 blob 清掉。"
|
||||
echo " 3) 确认它**不在**要推的范围里之后，再 push。"
|
||||
echo ""
|
||||
echo " （这条钩子的存在理由：判据读的是 index，只证明\"不会再被加回来\"；"
|
||||
echo " 而 blob 还躺在未推送的提交里，只有推送前拦得住。）"
|
||||
} >&2
|
||||
fi
|
||||
done
|
||||
done
|
||||
|
||||
exit "$problems"
|
||||
@ -23,6 +23,7 @@
|
||||
*/
|
||||
import assert from 'node:assert/strict';
|
||||
import { readdirSync, unlinkSync, writeFileSync } from 'node:fs';
|
||||
import { spawnSync } from 'node:child_process';
|
||||
import { dirname, join, relative } from 'node:path';
|
||||
import { test } from 'node:test';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
@ -32,6 +33,13 @@ import { code, prose, stripComments } from './lib/read.mjs';
|
||||
const HERE = dirname(fileURLToPath(import.meta.url));
|
||||
const RELECTRON = join(HERE, '..'); // test/ 的上一级就是 client/electron
|
||||
const SELF = join(HERE, 'lib', 'read.mjs');
|
||||
/** 仓库根 —— 从**本文件位置**推（这不是硬编码，是本判据要求的正确写法） */
|
||||
const REPO_ROOT = join(HERE, '..', '..', '..');
|
||||
|
||||
/** 跑一条 git 命令（在仓库根，拿字符串回来）。与 `commit-hygiene` 同形。 */
|
||||
function git(args) {
|
||||
return spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' });
|
||||
}
|
||||
|
||||
/**
|
||||
* 仓库目录名 —— 判"某条绝对路径是不是落在仓库内"用的**值**特征。
|
||||
@ -345,3 +353,51 @@ test('★ stripComments 必须保持行号（对所有真实判据文件，不
|
||||
* **这条限制没有判据**（写不出不靠词法分析就能判的形状），所以只能留成文字。
|
||||
*/
|
||||
});
|
||||
|
||||
/**
|
||||
* ★ AGC 真身**从未进过远端**（健全不变量：这个路径永远不该出现在 `origin/main` 历史里）。
|
||||
*
|
||||
* 为什么在 `commit-hygiene` 那条之外**还要**这一条 —— pi 2026-09-15 指出的洞：
|
||||
* 那条判据读的是 **index**（`git ls-files`），它守的是"**不会再被加回来**"，
|
||||
* **不是**"**不会被推出去**"。两者的差别在 `git rm --cached` 之后立刻可见：
|
||||
* 文件从 index 消失了（那条判据绿），可 **blob 还躺在未推送的提交里**（`7647c24`、`320c93f`），
|
||||
* 下一次 `git push` 会连它一起发出去，**而没有任何东西会红**。
|
||||
*
|
||||
* ★ 诚实说清它的性质（不夸大成"预防"）：
|
||||
* **它是在泄露之后响的闹钟。** 真到它红的那一天，东西已经出去了，
|
||||
* 处置方式必须是"按已泄露处理"（去 AGC 轮换），而不是"把它删掉再推"。
|
||||
* 真正的**预防**是 `.githooks/pre-push`（推送前拦下）—— 那条我已经做了，
|
||||
* 并且由 `deploy/install.sh --git-hooks` 接线。
|
||||
* 两条都要：钩子会被 `--no-verify` / 没装的机器绕过，**闹钟负责发现绕过**。
|
||||
*/
|
||||
test('★ AGC 真身从未进过远端历史（泄露之后响的闹钟，不是预防）', () => {
|
||||
const AGC_PATH = 'client/harmony/entry/src/main/resources/rawfile/agconnect-services.json';
|
||||
/*
|
||||
* 先用本地可达历史自检**探针本身**：如果连本地历史都查不出这条路径，
|
||||
* 说明 `git log -- <路径>` 这个查法在这棵树上根本不管用，那么下面的"远端为空"
|
||||
* 就毫无意义（**空与"探针坏了"必须分得开**）。本地历史里**确实**有它。
|
||||
*/
|
||||
const local = git(['log', '--all', '--oneline', '--', AGC_PATH]);
|
||||
assert.equal(local.status, 0, '要能跑 git log（否则这条判据无从判起）');
|
||||
assert.ok(local.stdout.trim().length > 0,
|
||||
'探针自检失败：**本地**历史里都查不到这条路径 —— 那么"远端为空"只是因为查法不管用，'
|
||||
+ '不是因为它没被推过。先修探针（`git log -- <路径>`），别把坏探针的空输出读成"安全"');
|
||||
|
||||
const rem = git(['remote', 'get-url', 'origin']);
|
||||
assert.equal(rem.status, 0,
|
||||
'这条判据要有一个名为 origin 的远端可比 —— 没有远端时"从未发布"无从判起，'
|
||||
+ '不要让它静默变成一条永远为空的假判据');
|
||||
|
||||
const published = git(['log', 'origin/main', '--oneline', '--', AGC_PATH]);
|
||||
assert.equal(published.status, 0,
|
||||
'要能查到 origin/main —— 查不到时不要当成"没有"（那是把"不知道"读成"安全"）');
|
||||
assert.equal(published.stdout.trim(), '',
|
||||
'AGC 客户端凭证的**真身已经进过远端历史** ——\n'
|
||||
+ ' 它含 `client_secret`/`api_key` 信封与明文 `client_id`/`app_id`，\n'
|
||||
+ ' 而本仓镜像是**匿名可 clone 的公开项目**（docs/GITCODE-MIRROR.md）。\n'
|
||||
+ ' ★ 处置**不是**"删掉再推"（历史里的 blob 撤不回）：按**已泄露**处理 ——\n'
|
||||
+ ' 1) 去 AGC 控制台**轮换** client_secret / api_key；\n'
|
||||
+ ' 2) 历史清理（filter-repo）+ 强推，并与所有 clone 过的人对齐；\n'
|
||||
+ ' 3) 查清是哪次 push 绕过了 `.githooks/pre-push`（`--no-verify`？没装的机器？）。\n'
|
||||
+ ` 涉及提交：\n ${published.stdout.trim().split('\n').join('\n ')}`);
|
||||
});
|
||||
|
||||
@ -85,7 +85,7 @@ const SUITE = [
|
||||
['test/debt-visibility.test.mjs', [], 1],
|
||||
['test/commit-hygiene.test.mjs', ['--experimental-strip-types', '--no-warnings'], 4],
|
||||
// 判据目录自身的卫生：读文本必须走 test/lib/read.mjs 的具名入口
|
||||
['test/criteria-hygiene.test.mjs', [], 5],
|
||||
['test/criteria-hygiene.test.mjs', [], 6],
|
||||
// 用户管理页（P4c 同批）：动作↔服务端调用同名 / 门禁只认严格 admin /
|
||||
// 启停只发 status / 「受限」徽标口径 / 页面零写死色值 / 接线（纯逻辑真被调用）
|
||||
['test/harmony-admin.test.mjs', ['--experimental-strip-types', '--no-warnings'], 22],
|
||||
|
||||
@ -37,16 +37,44 @@ ETC=/etc/agentmail
|
||||
CHECK_ONLY=0
|
||||
ALLOW_DIRTY=0
|
||||
ALLOW_STALE=0
|
||||
GIT_HOOKS=0
|
||||
for a in "$@"; do
|
||||
case "$a" in
|
||||
--check) CHECK_ONLY=1 ;;
|
||||
--allow-dirty) ALLOW_DIRTY=1 ;;
|
||||
--allow-stale) ALLOW_STALE=1 ;;
|
||||
--git-hooks) GIT_HOOKS=1 ;;
|
||||
-h|--help) sed -n '2,20p' "$0"; exit 0 ;;
|
||||
*) echo "未知参数：$a（支持 --check / --allow-dirty / --allow-stale）" >&2; exit 2 ;;
|
||||
*) echo "未知参数：$a（支持 --check / --allow-dirty / --allow-stale / --git-hooks）" >&2; exit 2 ;;
|
||||
esac
|
||||
done
|
||||
|
||||
# ── 版本库钩子：把 `core.hooksPath` 指向仓库里的 `.githooks/` ──
|
||||
#
|
||||
# 为什么要它、而不只靠判据（pi 2026-09-15）：
|
||||
# `criteria-hygiene` 里那条 AGC 判据读的是 **index**（`git ls-files`）——
|
||||
# 它守的是"不会再被加回来"，**不是**"不会被推出去"。而 blob 此刻正躺在
|
||||
# **未推送的提交**里：`git rm --cached` 之后它从 index 消失了，历史里却还在，
|
||||
# 下一次 `git push` 会连它一起发出去，**而没有任何东西会红**。
|
||||
# ⇒ 判据是**泄露之后**响的闹钟；这个钩子是**不让它泄露**。两件都要有。
|
||||
#
|
||||
# 钩子**跟着仓库走**（`.githooks/` 进版本库），所以换台机器 clone 下来装一次即可；
|
||||
# 这也是它比"写进 `.git/hooks/`"强的地方 —— 后者不进版本库、别人 clone 不到。
|
||||
if [[ $GIT_HOOKS -eq 1 ]]; then
|
||||
git -C "$REPO" config core.hooksPath .githooks
|
||||
echo "==> 已接 git 钩子：core.hooksPath=.githooks"
|
||||
# 自证：接上之后**真的要能拦**。只设配置不验证 = "门是好的 ≠ 门接着"。
|
||||
if [[ -x "$REPO/.githooks/pre-push" ]]; then
|
||||
echo " [ OK ] .githooks/pre-push 存在且可执行"
|
||||
else
|
||||
echo " [FAIL] .githooks/pre-push 不存在或不可执行 —— 配置指过去了也没有东西跑" >&2
|
||||
exit 1
|
||||
fi
|
||||
if [[ $CHECK_ONLY -eq 0 ]]; then
|
||||
exit 0 # --git-hooks 是独立动作，不连带装服务
|
||||
fi
|
||||
fi
|
||||
|
||||
# ★ **部署锁**（pi 评审 2026-09-14）：环境前提里原先缺的第五列 —— **同时性**。
|
||||
# 这台机器的工作区是多 agent 共用的（docs/DEV-TOOLING.md 自己记过），并发部署会互相踩：
|
||||
# 两次写同一个目录/文件、两次后置验证互相把对方的"验证不过"当自己的结论、谁回滚不确定。
|
||||
@ -234,6 +262,22 @@ if [[ -d "$PI_SDK" ]]; then
|
||||
fi
|
||||
|
||||
if [[ $CHECK_ONLY -eq 1 ]]; then
|
||||
# ★ 版本库钩子装上了吗 —— **门自己的接线**也要验。
|
||||
#
|
||||
# 为什么放在这一相位（pi 2026-09-15 指出"判据只盖索引、盖不住 push"）：
|
||||
# `criteria-hygiene` 里那条 AGC 判据读的是 **index**，它只证明"不会再被加回来"；
|
||||
# 而 blob 还躺在**未推送的提交**里，下一次 `git push` 会连它一起发出去。
|
||||
# 拦得住这一步的只有 `.githooks/pre-push` —— 而**没装上的钩子等于没有钩子**。
|
||||
# 这与 `--check` 存在的理由是同一条：**门是好的 ≠ 门接着**。
|
||||
hooks_path="$(git -C "$REPO" config --get core.hooksPath || true)"
|
||||
if [[ "$hooks_path" == ".githooks" ]]; then
|
||||
echo " [ OK ] git 钩子已接（core.hooksPath=.githooks，pre-push 会拦 AGC 真身）"
|
||||
else
|
||||
echo " [WARN] git 钩子**没接**：core.hooksPath=${hooks_path:-（未设 → 用 .git/hooks，里面只有 sample）}"
|
||||
echo " 后果：推送前**没有任何东西**拦 AGC 真身进远端历史（判据只盖 index，盖不住 push）。"
|
||||
echo " 接上：./deploy/install.sh --git-hooks（只写本地 git 配置，不需要 root）"
|
||||
fi
|
||||
|
||||
# ★ `go vet`/`go test` 提到这个相位来跑（pi 评审 2026-09-14）。
|
||||
#
|
||||
# 原先的措辞是"**所有会红的门禁都跑过了**（前端 typecheck/test/build、共用模块同源、
|
||||
|
||||
Reference in New Issue
Block a user