Initial import of streamline

This commit is contained in:
2026-11-16 17:26:44 -08:00
commit 8e4aec1855
1221 changed files with 274256 additions and 0 deletions
+345
View File
@@ -0,0 +1,345 @@
/**
* `wait-for` 的行为测试。
*
* 这个工具存在的唯一理由是「agent 敢把一个长等待交给它,而不是回去自己写轮询」。
* 所以这里断言的不是"它能等",而是它在每一种收尾下**都给出足以继续决策的输出**:
* 达成和超时要能区分(0 / 124),超时也要带上日志尾巴,probe 自己坏掉不能被当成
* "条件没达成"。少了任何一条,agent 都会退回去一格一格地 poll —— 那正是它要消灭的。
*
* 用真进程跑,不 mock:被测的东西就是子进程、退出码和超时,mock 掉就什么也没测。
* 每个用例都钉在秒级,整支跑完 ~6s。
*/
import { describe, expect, test, beforeAll, afterAll } from "bun:test";
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import path from "node:path";
import { ensureWaitBlockInPrompt, waitPromptBlock } from "@bbbug/shared/wait_prompt";
const BIN = path.resolve(import.meta.dir, "../../bin/wait-for.ts");
let dir = "";
beforeAll(() => { dir = mkdtempSync(path.join(tmpdir(), "waitfor-")); });
afterAll(() => { rmSync(dir, { recursive: true, force: true }); });
async function run(args: string[]): Promise<{ code: number; out: string }> {
const p = Bun.spawn([process.execPath, BIN, ...args], { stdout: "pipe", stderr: "pipe" });
const [out, err] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
return { code: await p.exited, out: out + err };
}
describe("wait-for", () => {
test("--until 条件立刻成立时秒退,退出码 0", async () => {
const t0 = Date.now();
const r = await run(["--until", "true", "--timeout", "10s"]);
expect(r.code).toBe(0);
expect(r.out).toContain("条件达成");
// 首分钟走 3s 快探,但第一次探测是立即的 —— 不该先睡一觉再看。
expect(Date.now() - t0).toBeLessThan(3000);
});
test("条件一直不成立 → 退出码 124,且明说这不等于失败", async () => {
const r = await run(["--until", "false", "--timeout", "2s", "--interval", "1s", "--quiet"]);
expect(r.code).toBe(124);
expect(r.out).toContain("未达成");
// 这句是防「等超时了就写成环境阻塞」的护栏,比退出码更要紧。
expect(r.out).toContain("环境阻塞");
});
test("--file 等文件出现:先不在,中途落下来", async () => {
const f = path.join(dir, "late.txt");
setTimeout(() => writeFileSync(f, "done\n"), 1200);
const r = await run(["--file", f, "--timeout", "15s", "--quiet"]);
expect(r.code).toBe(0);
}, 20_000);
test("--file + --match:文件在但内容没命中时继续等", async () => {
const f = path.join(dir, "log.txt");
writeFileSync(f, "building…\n");
setTimeout(() => writeFileSync(f, "building…\npull success\n"), 1200);
const r = await run(["--file", f, "--match", "pull success", "--timeout", "15s", "--quiet"]);
expect(r.code).toBe(0);
}, 20_000);
test("--tail 在达成时把日志尾巴一起打出来(省掉紧随其后的那次 tail 调用)", async () => {
const f = path.join(dir, "build.log");
writeFileSync(f, ["a", "b", "BUILD SUCCEEDED"].join("\n") + "\n");
const r = await run(["--until", "true", "--tail", f, "--tail-lines", "2", "--quiet"]);
expect(r.code).toBe(0);
expect(r.out).toContain("BUILD SUCCEEDED");
expect(r.out).not.toContain("\na\n"); // 只要末 2 行
});
test("超时同样带日志尾巴 —— 超时那一刻恰恰最需要看日志", async () => {
const f = path.join(dir, "stuck.log");
writeFileSync(f, "linking…\n");
const r = await run(["--until", "false", "--timeout", "2s", "--tail", f, "--quiet"]);
expect(r.code).toBe(124);
expect(r.out).toContain("linking…");
});
test("--pgrep:没有匹配进程时立刻达成", async () => {
const r = await run(["--pgrep", "zzz-no-such-process-zzz", "--timeout", "5s", "--quiet"]);
expect(r.code).toBe(0);
});
test("--while:probe 退出 0 表示还在跑,非 0 才算完", async () => {
const f = path.join(dir, "flag");
writeFileSync(f, "x");
setTimeout(() => rmSync(f, { force: true }), 1200);
const r = await run(["--while", `test -f ${f}`, "--timeout", "15s", "--quiet"]);
expect(r.code).toBe(0);
}, 20_000);
test("probe 是个不存在的命令:sh 返回 127 = 条件未达成,不能被当成达成", async () => {
// sh 对未知命令返回 127(非 0)= 条件未达成,不是 probe 故障;真正的故障是 probe 卡死。
// 这里断言它没有把 127 误判成「达成」。
const r = await run(["--until", "definitely-not-a-command-xyz", "--timeout", "2s", "--quiet"]);
expect(r.code).toBe(124);
}, 15_000);
test("probe 自己卡死不会卡住整个等待:单次 probe 有独立上限", async () => {
const t0 = Date.now();
// probe 每次都要睡 30s,--probe-timeout 必须把它掐断,否则整体会被拖到 30s 以上。
const r = await run(["--until", "sleep 30", "--timeout", "3s", "--probe-timeout", "500ms", "--quiet"]);
expect(r.code).toBe(124);
expect(Date.now() - t0).toBeLessThan(15_000);
}, 25_000);
test("互斥与必填:没给条件、或给了两个,都是用法错(2)", async () => {
expect((await run(["--timeout", "5s"])).code).toBe(2);
expect((await run(["--until", "true", "--file", "/tmp/x"])).code).toBe(2);
});
test("时长写错要当场报错,不能按默认值静悄悄跑 30 分钟", async () => {
const r = await run(["--until", "true", "--timeout", "45minutes"]);
expect(r.code).toBe(2);
expect(r.out).toContain("--timeout");
});
// ── --run:起一个长命令并等它跑完 ───────────────────────────────────────
// 这一组盯的是「不谎报成败」。语料里的构建壳有五种写法,搓错一次白烧 25 分钟,
// 所以退出码必须是真的,超时必须不杀命令。
test("--run 跑完并报出真实退出码 0", async () => {
const r = await run(["--run", "echo hello; echo world", "--timeout", "20s", "--quiet"]);
expect(r.code).toBe(0);
expect(r.out).toContain("退出码 0");
expect(r.out).toContain("world"); // 日志尾巴自带,不用再发一次 tail
}, 30_000);
test("命令里的 exit N 必须原样报出来,不能变成「拿不到退出码」", async () => {
// 曾经的真 bug:用 `{ cmd; }` 包,命令里的 `exit 7` 把整个 shell 退掉,
// 写退出码那一句永远跑不到 —— 每一次失败都被报成「拿不到」。
const r = await run(["--run", "echo building; exit 7", "--timeout", "20s", "--quiet"]);
expect(r.code).toBe(1);
expect(r.out).toContain("退出码 7");
expect(r.out).not.toContain("拿不到退出码");
}, 30_000);
test("日志里出现 error: 但命令成功时,不能报成失败", async () => {
// 构建日志里出现 "error:" 太常见(警告、第三方输出)。靠 grep 猜成败会把
// 成功的构建报成失败,更糟的是反过来。所以只认退出码。
const r = await run(["--run", "echo 'note: error: deprecated API'; exit 0", "--timeout", "20s", "--quiet"]);
expect(r.code).toBe(0);
expect(r.out).toContain("退出码 0");
}, 30_000);
test("--log 指定日志路径,并把 stderr 也收进去", async () => {
const f = path.join(dir, "build-r2.log");
const r = await run(["--run", "echo out; echo err 1>&2", "--log", f, "--timeout", "20s", "--quiet"]);
expect(r.code).toBe(0);
const body = readFileSync(f, "utf8");
expect(body).toContain("out");
expect(body).toContain("err");
}, 30_000);
test("超时不杀命令,并给出续等的现成命令", async () => {
const f = path.join(dir, "slow.log");
const r = await run(["--run", "sleep 20; echo finished", "--log", f, "--timeout", "2s", "--quiet"]);
expect(r.code).toBe(124);
expect(r.out).toContain("没有杀它");
expect(r.out).toContain("--pid "); // 续等命令
// 真的还活着:等它自己跑完,日志里应当出现结果
await new Promise((res) => setTimeout(res, 22_000));
expect(readFileSync(f, "utf8")).toContain("finished");
}, 45_000);
test("--run 与其它条件互斥", async () => {
expect((await run(["--run", "true", "--until", "true"])).code).toBe(2);
});
test("--label 出现在输出里,便于在会话日志里认出在等什么", async () => {
const r = await run(["--until", "true", "--label", "iOS clean build", "--quiet"]);
expect(r.out).toContain("[iOS clean build]");
});
});
/**
* 这一组测的不是工具,是「改了默认就真的生效」。
*
* 生产跑的是 agent_prompts 里 active 指向的模板版本,那些版本是在这个小节存在
* 之前存的,里面没有 {{waitBlock}} 占位符。只改内置默认的话,工具部署到每台节点、
* 而没有一个 agent 被告知它存在 —— 看起来上线了,实际什么也没发生。
* ensureWaitBlockInPrompt 就是堵这个洞的,与 ensureDeviceBlockInPrompt /
* ensureKbInPrompt 同一套做法。
*/
describe("ensureWaitBlockInPrompt", () => {
const BLOCK = "## 等构建 / 拉包 / 部署 —— 不要自己写轮询循环\n\n用 wait-for。\n\n";
test("老模板没有占位符 → 仍然把小节插进去", () => {
const old = "## 步骤 2 — 判断本批是否接着上一批修\n略。\n\n## 步骤 3 — 复现、修复、验证\n正文。\n";
const out = ensureWaitBlockInPrompt(old, BLOCK);
expect(out).toContain("## 等构建 / 拉包 / 部署");
// 插在「步骤 3」之前 —— agent 正要开始构建的位置
expect(out.indexOf("## 等构建")).toBeLessThan(out.indexOf("## 步骤 3"));
expect(out).toContain("## 步骤 2");
});
test("模板已有这一小节 → 不重复插第二份", () => {
const already = `前言\n\n${BLOCK}## 步骤 3 — 复现\n正文\n`;
const out = ensureWaitBlockInPrompt(already, BLOCK);
expect(out).toBe(already);
expect(out.split("## 等构建").length - 1).toBe(1);
});
test("人工改过措辞也算已有,不覆盖别人的编辑", () => {
const edited = "## 等构建 / 拉包 / 部署(本节点特调)\n只准用 wait-for。\n\n## 步骤 3 — 复现\n";
expect(ensureWaitBlockInPrompt(edited, BLOCK)).toBe(edited);
});
test("security 模板的锚点是「运行规则」", () => {
const sec = "前言\n\n## 运行规则\n- 按 SecuritySpec 走\n";
const out = ensureWaitBlockInPrompt(sec, BLOCK);
expect(out.indexOf("## 等构建")).toBeLessThan(out.indexOf("## 运行规则"));
});
test("英文模板走英文锚点", () => {
const en = "Intro\n\n## Step 3 — implement and verify\nbody\n";
const out = ensureWaitBlockInPrompt(en, BLOCK);
expect(out.indexOf("## 等构建")).toBeLessThan(out.indexOf("## Step 3"));
});
test("模板被改得认不出锚点 → 追加到末尾,而不是丢掉", () => {
const weird = "完全自定义的模板正文,没有任何标准小标题。\n";
const out = ensureWaitBlockInPrompt(weird, BLOCK);
expect(out).toContain("## 等构建 / 拉包 / 部署");
expect(out.startsWith("完全自定义")).toBe(true);
});
test("block 为空时什么都不做", () => {
const t = "## 步骤 3 — 复现\n";
expect(ensureWaitBlockInPrompt(t, "")).toBe(t);
});
// 上面几条用的是手写的小节,标题恰好是旧标记 —— 所以真实小节的标题和标记对不上时
// 没有一条测试会红,线上每份执行 prompt 都被插了第二份(09-14 → 10-02)。这里用真实生成的小节。
test.each(["zh", "en"] as const)("真实生成的小节(%s)已在 prompt 里 → 不插第二份", (lang) => {
const real = waitPromptBlock({ cmd: "bun satellite.js wait-for", lang });
const step3 = lang === "zh" ? "## 步骤 3 — 复现、修复、验证\n" : "## Step 3 — reproduce, fix, verify\n";
const rendered = `前言\n\n${real}${step3}正文\n`;
expect(ensureWaitBlockInPrompt(rendered, real)).toBe(rendered);
});
});
/**
* 失败时打更多日志 —— 上线首日的实测反馈。
*
* 2026-09-15,上线后 19 个执行轮里有 25 次调用是在 wait-for 之后**再去读它自己那份
* 日志**(`tail -c 4000 "$L"`、`grep -i "no space|Internal compiler error"`、
* `sed -n '30,90p'`)。「省掉紧随其后那次 tail」是这个工具的卖点之一,而它恰恰在
* 最需要的时候(构建挂了)没兑现:默认 20 行里通常只有收尾噪音,真正的报错在更上面。
*/
describe("失败时的日志行数", () => {
const manyLines = (n: number) => Array.from({ length: n }, (_, i) => `line-${i + 1}`).join("\n") + "\n";
test("成功时仍然只打 20 行 —— 成功不需要翻历史", async () => {
const f = path.join(dir, "ok.log");
writeFileSync(f, manyLines(200));
const r = await run(["--until", "true", "--tail", f, "--quiet"]);
expect(r.out).toContain("line-200");
expect(r.out).toContain("line-181");
expect(r.out).not.toContain("line-180"); // 第 21 行往上不打
}, 20_000);
test("命令失败时自动打到 80 行", async () => {
// 输入和 --log 必须是两个文件:让命令 cat 自己的日志会边读边写,永不结束。
const src = path.join(dir, "fail-src.txt");
const log = path.join(dir, "fail.log");
writeFileSync(src, manyLines(200));
const r = await run(["--run", `cat ${src}; exit 2`, "--log", log, "--quiet"]);
expect(r.code).toBe(1);
expect(r.out).toContain("退出码 2");
expect(r.out).toContain("末 80 行");
expect(r.out).toContain("line-121"); // 末 80 行的第一行
expect(r.out).not.toContain("line-120");
}, 30_000);
test("超时时也打 80 行 —— 超时那一刻最需要看日志", async () => {
const f = path.join(dir, "slowfail.log");
writeFileSync(f, manyLines(200));
const r = await run(["--until", "false", "--timeout", "2s", "--tail", f, "--quiet"]);
expect(r.code).toBe(124);
expect(r.out).toContain("line-121"); // 末 80 行的第一行
expect(r.out).not.toContain("line-120");
}, 20_000);
test("显式传了 --tail-lines 就一律听用户的,失败时也不擅自加码", async () => {
const f = path.join(dir, "explicit.log");
writeFileSync(f, manyLines(200));
const r = await run(["--until", "false", "--timeout", "2s", "--tail", f, "--tail-lines", "5", "--quiet"]);
expect(r.code).toBe(124);
expect(r.out).toContain("line-196");
expect(r.out).not.toContain("line-195");
}, 20_000);
});
/**
* 设备 UI 状态的边界 —— 上线三天后量出来的误用。
*
* 66 个执行轮里 33 次超时、烧掉 4.4 小时,清一色是拿 --until 等设备 UI:
* `catuse apps | grep -q TikTokBase`、`dumpsys window | grep -q mCurrentFocus`、
* `uiautomator dump | grep -q …`,超时值 3–8 分钟(UI 尺度,不是构建尺度)。
*
* 构建有确定的终点,UI 状态没有。把可观察的轮询换成盲等,在这个场景下是净损失。
* 所以:**警告,不拦截** —— 拦截会把 agent 逼去找绕过写法。
*/
describe("等设备 UI 状态时要警告", () => {
const DEVICE_PROBES = [
"catuse apps 2>/dev/null | grep -q TikTokBase",
'adb shell dumpsys window | grep -q "mCurrentFocus=Window.*musically"',
'adb shell "uiautomator dump /sdcard/b2.xml >/dev/null; grep -q Profile /sdcard/b2.xml"',
];
for (const probe of DEVICE_PROBES) {
test(`--until 等 UI 状态会警告: ${probe.slice(0, 34)}…`, async () => {
const r = await run(["--until", probe, "--timeout", "2s", "--quiet"]);
expect(r.code).toBe(124);
expect(r.out).toContain("设备 UI 状态");
expect(r.out).toContain("catuse ui");
// 超时时再说一次,而且是针对性的:别调大 timeout 重来
expect(r.out).toContain("再等下去多半也不会变");
expect(r.out).not.toContain("调大 --timeout;"); // 通用那句不该出现
}, 20_000);
}
test("构建类 probe 不触发警告 —— 别把正常用法也吵一遍", async () => {
const r = await run(["--until", "test -f /tmp/definitely-not-there.exit", "--timeout", "2s", "--quiet"]);
expect(r.code).toBe(124);
expect(r.out).not.toContain("设备 UI 状态");
expect(r.out).toContain("不要改成「环境阻塞」"); // 仍给通用引导
}, 20_000);
test("--run 跑一条 adb 命令是正常用法,不该被警告", async () => {
// 装包、点一下、起 App 都是 --run 的正当场景;只有「轮询一个 UI 条件」才是误用。
const r = await run(["--run", "echo 'adb shell dumpsys window'", "--timeout", "15s", "--quiet"]);
expect(r.code).toBe(0);
expect(r.out).not.toContain("设备 UI 状态");
}, 25_000);
test("警告不拦截 —— 条件真达成时照常返回 0", async () => {
const r = await run(["--until", "catuse apps | grep -q x || true", "--timeout", "10s", "--quiet"]);
expect(r.code).toBe(0);
expect(r.out).toContain("设备 UI 状态"); // 警告仍打,但没挡住
expect(r.out).toContain("条件达成");
}, 20_000);
});