ci: 让测试真的跑起来（Gitea Actions + pre-push 钩子）

`node --test tests/` 在 Node 22 上根本不工作 —— Node 把路径当模块加载，
报 "Cannot find module .../tests"，退出码 1，零个测试执行。而这条命令在
CLAUDE.md 里被当作标准用法记了很久。这大概就是这套断言从来没人跑起来的
一个主要原因：照文档敲，得到一个看不懂的错误。

正确形式是裸 `node --test`（自动发现 **/*.test.mjs）。四处全改，并加断言
钉住 —— 我自己第一版钩子和 workflow 也照抄了那个错误形式，实测才发现
它会无条件拦住每一次 push。

- .gitea/workflows/tests.yml：Gitea 原生位置。用 node 容器而非 setup-node，
  自建 Gitea 上后者要从 GitHub 拉，是新 runner 上又一个可能缺的东西。
  容器 tag 与 NODE_VERSION 绑定，否则 CI 测的运行时和出货的不是一个。
- .github/workflows/tests.yml：镜像一份，断言保证两边执行内容一致。
- .githooks/pre-push：不依赖任何 runner 的兜底。实测过它会拦下失败的 push。
  写明 --no-verify 怎么跳过 —— 拦不掉的钩子会被第一个被卡住的人删掉。

为什么需要钩子这一层：这台 Gitea 的 Actions 是开着的，但推上去的 workflow
产生了 0 次运行（total_count: 0），runner API 要鉴权查不了，最可能是没注册
runner。钩子是唯一完全不需要服务端支持的一层。

CLAUDE.md 补上 `git config core.hooksPath .githooks` —— 钩子是 per-clone 的，
没人替你装。

.gitea/workflows/tests.yml

@@ -0,0 +1,34 @@
+name: Tests
+
+# Gitea reads both .gitea/workflows/ and .github/workflows/, but which one a given
+# instance scans depends on its config — so the workflow lives here, in Gitea's
+# native location, and .github/workflows/tests.yml stays as a copy for if we ever
+# move back to GitHub. tests/ci-parity.test.mjs keeps the two identical.
+#
+# Runs in a node container rather than using setup-node: on a self-hosted Gitea
+# the action has to be fetched from GitHub, which is one more thing that can be
+# missing on a fresh runner.
+on:
+  push:
+    branches: ['**']
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    container:
+      image: node:22.22.1
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Node version
+        run: node --version
+
+      - name: Generated files are up to date
+        run: node portable/lib/i18n/build-messages.mjs --check
+
+      - name: Tests
+        # Bare `node --test` discovers **/*.test.mjs. `node --test tests/` fails
+        # with "Cannot find module" — Node reads the path as a module, not a dir.
+        run: node --test

.githooks/pre-push

@@ -0,0 +1,49 @@
+#!/bin/sh
+# Runs the test suite before anything leaves this machine.
+#
+# This exists because CI cannot be relied on here. The suite sat unrun for the
+# whole life of the upstream project — nothing invoked `node --test`, so every
+# assertion in tests/ was decoration. We wired up a workflow, and on our own
+# Gitea it produced zero runs, most likely because no runner is registered.
+#
+# A hook is not a substitute for CI: it only protects the machine it is installed
+# on, and --no-verify skips it. But it is the one layer that works with no server
+# support at all, and it turns "the tests exist" back into "the tests ran".
+#
+# Install:  git config core.hooksPath .githooks
+# Skip once (say the push is docs-only and node is unavailable):
+#           git push --no-verify
+
+set -e
+
+if ! command -v node >/dev/null 2>&1; then
+    echo "pre-push: node not found, skipping tests." >&2
+    echo "          Run them wherever you do have node before merging." >&2
+    exit 0
+fi
+
+echo "pre-push: checking generated files are up to date…"
+if ! node portable/lib/i18n/build-messages.mjs --check; then
+    echo "" >&2
+    echo "pre-push: generated files are stale." >&2
+    echo "          Run: node portable/lib/i18n/build-messages.mjs" >&2
+    exit 1
+fi
+
+echo "pre-push: running tests…"
+# Bare `node --test` discovers **/*.test.mjs. `node --test tests/` does not work:
+# Node treats the path as a module to load and dies with "Cannot find module".
+# That form was in CLAUDE.md for the life of the project, which is a good part of
+# why nobody ever got the suite to run.
+if ! node --test > /tmp/uclaw-prepush.log 2>&1; then
+    echo "" >&2
+    tail -40 /tmp/uclaw-prepush.log >&2
+    echo "" >&2
+    echo "pre-push: tests failed, push aborted." >&2
+    echo "          Full output: /tmp/uclaw-prepush.log" >&2
+    echo "          To push anyway: git push --no-verify" >&2
+    exit 1
+fi
+
+passed=$(grep -oE '^# pass [0-9]+' /tmp/uclaw-prepush.log | grep -oE '[0-9]+' || echo '?')
+echo "pre-push: $passed tests passed."

.github/workflows/tests.yml

@@ -1,8 +1,9 @@
 name: Tests
 
-# The launcher/manifest tests were previously local-only — nothing ran them in CI,
-# so the guards they encode (pure-ASCII .bat, LF-only .command, no China-routed
-# download sources, installer parity) could regress unnoticed on a merge.
+# Copy of .gitea/workflows/tests.yml, kept for if we ever move back to GitHub.
+# Gitea reads both locations but which one a given instance scans depends on its
+# config, so the workflow lives in .gitea/ and this is the mirror.
+# tests/ci-parity.test.mjs keeps the two running the same thing.
 on:
   push:
     branches: ['**']
@@ -12,13 +13,18 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    container:
+      image: node:22.22.1
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22.22.1'
-          registry-url: 'https://registry.npmjs.org'
+      - name: Node version
+        run: node --version
 
-      - name: Run tests
-        run: node --test tests/
+      - name: Generated files are up to date
+        run: node portable/lib/i18n/build-messages.mjs --check
+
+      - name: Tests
+        # Bare `node --test` discovers **/*.test.mjs. `node --test tests/` fails
+        # with "Cannot find module" — Node reads the path as a module, not a dir.
+        run: node --test

CLAUDE.md

@@ -52,8 +52,12 @@ cd bootable
 ### Tests
 
 ```bash
-node --test tests/              # Run all tests (node:test, no test framework dep)
-node --test tests/windows-launchers.test.mjs   # Run one test file
+node --test                     # Run every test (node:test, no framework dependency)
+node --test tests/windows-launchers.test.mjs   # Run one file
+
+# NOT `node --test tests/` — Node reads that path as a module to load and dies
+# with "Cannot find module". That form was documented here for years, which is
+# a good part of why the suite went unrun.
 ```
 
 Tests assert on the **text/behavior of the launchers and shared `.mjs` helpers** — e.g. that the
@@ -61,8 +65,22 @@ Start launchers stay thin shells over `lib/start.mjs`, that `.bat` files are pur
 that no China-routed download source comes back, that the two installers resolve skills the same
 way, and that every message key exists in every catalogue. They read repo files as strings; they
 do **not** spawn OpenClaw. There is no root
-`package.json`. **As of 2026-08-17 tests do run in CI** — `.github/workflows/tests.yml` runs
-`node --test tests/` on every push and PR. Before that they were local-only, so the guards they
+`package.json`.
+
+**Enable the pre-push hook after cloning** — it is per-clone and nothing installs it for you:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+It runs the suite and the generated-file check before anything leaves your machine.
+`git push --no-verify` skips it. This matters because CI cannot be relied on here:
+the suite went unrun for the whole life of the upstream project, and on our own
+Gitea the workflow produced zero runs — most likely no runner is registered. The
+hook is the one layer that works with no server support at all.
+
+**As of 2026-08-17 tests also run in CI where a runner exists** — `.github/workflows/tests.yml` runs
+`node --test` on every push and PR. Before that they were local-only, so the guards they
 encode could regress unnoticed.
 
 **CI workflows** (`.github/workflows/`): `release.yml` builds Win/Mac portable + desktop and

tests/ci-parity.test.mjs

@@ -0,0 +1,89 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+const read = (...parts) => readFileSync(join(repoRoot, ...parts), 'utf8');
+
+// The suite went unrun for the whole life of the upstream project: nothing
+// invoked `node --test`, so every assertion in tests/ was decoration. These
+// checks are about the machinery that runs the tests, not the product.
+
+test('the workflow exists in both places Gitea might scan', () => {
+  // Which location a Gitea instance picks up depends on its config, and we
+  // cannot verify the server's config from here.
+  for (const path of [['.gitea', 'workflows', 'tests.yml'], ['.github', 'workflows', 'tests.yml']]) {
+    assert.ok(existsSync(join(repoRoot, ...path)), `${path.join('/')} is missing`);
+  }
+});
+
+test('both copies of the workflow run the same thing', () => {
+  const steps = (yaml) =>
+    [...yaml.matchAll(/^\s+run:\s*(.+)$/gm)].map((m) => m[1].trim());
+  const gitea = steps(read('.gitea', 'workflows', 'tests.yml'));
+  const github = steps(read('.github', 'workflows', 'tests.yml'));
+  assert.deepEqual(gitea, github, 'the two workflow copies have drifted apart');
+  // Bare `node --test`, not `node --test tests/` — see the assertion below.
+  assert.ok(gitea.some((s) => /node --test\s*$/.test(s)), 'neither copy actually runs the tests');
+  assert.ok(gitea.some((s) => s.includes('--check')), 'neither copy checks the generated files');
+});
+
+test('the workflow does not depend on a runner fetching setup actions', () => {
+  // On a self-hosted Gitea, setup-node has to be pulled from GitHub. A node
+  // container removes one thing that can be missing on a fresh runner.
+  const yaml = read('.gitea', 'workflows', 'tests.yml');
+  // Comments discuss setup-node on purpose; only the steps matter.
+  const steps = yaml.split(/\r?\n/).filter((line) => !line.trim().startsWith('#')).join('\n');
+  assert.doesNotMatch(steps, /setup-node/, 'prefer a node container over setup-node here');
+  assert.match(steps, /image:\s*node:/, 'the job should run in a node container');
+
+  // The container tag has to match what we pin, or CI tests a different runtime
+  // than the product ships.
+  const pinned = read('NODE_VERSION').trim().replace(/^v/, '');
+  assert.match(
+    steps,
+    new RegExp(`image:\\s*node:${pinned.replace(/\./g, '\\.')}`),
+    `the container should be node:${pinned} to match NODE_VERSION`,
+  );
+});
+
+test('a pre-push hook backs CI up, and says how to skip it', () => {
+  const hook = read('.githooks', 'pre-push');
+  assert.match(hook, /node --test tests\//, 'the hook should run the suite');
+  assert.match(hook, /build-messages\.mjs --check/, 'the hook should catch stale generated files');
+  // A hook that cannot be bypassed gets deleted by the first person it blocks
+  // at a bad moment.
+  assert.match(hook, /--no-verify/, 'the hook should document how to skip it');
+  // It must not pretend to have passed when node is unavailable.
+  assert.match(hook, /skipping tests/, 'the hook should say so when it cannot run');
+});
+
+test('the hook is documented where someone cloning will see it', () => {
+  // A hook nobody installs protects nobody. core.hooksPath is per-clone.
+  const claude = read('CLAUDE.md');
+  assert.match(claude, /core\.hooksPath/, 'CLAUDE.md should say how to enable the hook');
+});
+
+test('nothing invokes the form of node --test that does not work', () => {
+  // `node --test tests/` makes Node load the path as a module: "Cannot find
+  // module .../tests", exit 1, zero tests run. It was the documented command in
+  // CLAUDE.md for the life of the project — which is a good part of why the
+  // suite went unrun. Bare `node --test` discovers **/*.test.mjs correctly.
+  const offenders = [];
+  for (const path of [
+    ['.githooks', 'pre-push'],
+    ['.gitea', 'workflows', 'tests.yml'],
+    ['.github', 'workflows', 'tests.yml'],
+    ['CLAUDE.md'],
+  ]) {
+    read(...path).split(/\r?\n/).forEach((line, i) => {
+      // A bare directory argument. Naming a specific .mjs file is fine.
+      if (/node --test\s+tests\/\s*($|[>|&])/.test(line)) {
+        offenders.push(`${path.join('/')}:${i + 1}`);
+      }
+    });
+  }
+  assert.deepEqual(offenders, [], `these run a form that executes nothing:\n${offenders.join('\n')}`);
+});