mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-08 23:43:59 +00:00
14eb460dd2
* feat(scripts): serialize pr prepare gates and add remote testbox test gate Concurrent scripts/pr gate runs across .worktrees queued on the shared heavy-check lock mid-test: the queued run's children hit the 10-minute lock timeout while its unlocked build stage piled CPU load onto the holder's vitest shards, which then stalled past the 120s no-output watchdog and were SIGTERMed with zero real test failures (observed landing PRs #99935/#100026 on a loaded maintainer Mac). - scripts/pr-gates-lock.mjs holds the shared heavy-check lock for the whole local gate block; gate stages inherit the existing *_LOCK_HELD child contract, so concurrent gate runs now queue as whole units before their first command. - OPENCLAW_PR_GATES_REMOTE=testbox runs the full-suite pnpm test gate on a Blacksmith Testbox via scripts/crabbox-wrapper.mjs (same delegation as check:changed). The tbx_ lease id and Actions run URL from the crabbox --timing-json report are recorded in .local/gates.env (REMOTE_GATES_*) and .local/prep.md. Local remains the default; pnpm build/check stay local. Formatting verified with the primary checkout's oxfmt (hook bypassed: linked worktree has no hydrated node_modules). * fix(scripts): refresh the gate stamp when lease-retry gates rerun for a rebased head The lease-retry path reran build/check/test for the rebased prep head but left .local/gates.env describing the pre-push head, so prep.md/prep.env attributed stale evidence (including the new remote testbox lease id) to the pushed commit. Extract write_gates_env_stamp as the single stamp writer, rewrite the stamp from the retry path for all modes, and re-source gates.env in prepare_push after the push settles. Found by autoreview (codex/gpt-5.5); formatting verified with the primary checkout's oxfmt (hook bypassed: linked worktree has no node_modules). * fix(scripts): harden remote PR gate evidence * fix(scripts): serialize complete gate setup * fix(scripts): clear stale docs gate proof
35 lines
2.8 KiB
Markdown
35 lines
2.8 KiB
Markdown
# Scripts Guide
|
|
|
|
This directory owns local tooling, script wrappers, and generated-artifact helper rules.
|
|
|
|
## Wrapper Rules
|
|
|
|
- Prefer existing wrappers over raw tool entrypoints when the repo already has a curated seam.
|
|
- For tests, prefer `scripts/run-vitest.mjs` or the root `pnpm test ...` entrypoints over raw `vitest run` calls.
|
|
- Never use bare `vitest ...` in automation; it starts local watch mode unless `run` or `--run` is explicit.
|
|
- For lint/typecheck flows, prefer `scripts/run-oxlint.mjs` and `scripts/run-tsgo.mjs` when adding or editing package scripts or CI steps that should honor repo-local runtime behavior.
|
|
- For changed-file verification, prefer `scripts/check-changed.mjs` and keep lane classification in `scripts/changed-lanes.mjs`. Use `node scripts/check-changed.mjs --dry-run [--staged|-- <files...>]` to inspect the plan before running anything expensive. Do not copy path-scope rules into new hooks or ad hoc CI snippets.
|
|
- For one/few lint files, prefer direct `node scripts/run-oxlint.mjs --tsconfig <matching config> <files...>` over sharded `pnpm lint`; `check-changed.mjs` owns this targeting for core, extension, and script diffs.
|
|
|
|
## Local Heavy-Check Lock
|
|
|
|
- Respect the local heavy-check lock behavior in `scripts/lib/local-heavy-check-runtime.mjs`.
|
|
- Do not bypass that lock for real heavy commands just to make a local loop look faster.
|
|
- Metadata-only or explicitly narrow commands may skip the lock when the existing helper logic says that is safe.
|
|
- If you change the lock heuristics, add or update the narrow tests under `test/scripts/`.
|
|
|
|
## PR Prepare Gates
|
|
|
|
- `scripts/pr prepare-gates` holds the heavy-check lock for its whole local gate block (`scripts/pr-gates-lock.mjs`), so concurrent gate runs across `.worktrees` queue as units instead of dying on child lock timeouts or vitest no-output watchdog kills.
|
|
- `OPENCLAW_PR_GATES_REMOTE=testbox` runs the full-suite `pnpm test` gate on a Blacksmith Testbox through `scripts/crabbox-wrapper.mjs` (same delegation as `check:changed`); `pnpm build`/`pnpm check` stay local. The `tbx_` lease id and Actions run URL land in `.local/gates.env` (`REMOTE_GATES_*`) and `.local/prep.md`. Use it for reviewed trusted code when a loaded host makes the local 88-shard run stall-kill; contributor/fork code stays on secretless CI or sanitized AWS unless a maintainer explicitly approves credentialed execution.
|
|
|
|
## Generated Outputs
|
|
|
|
- If a script writes generated artifacts, keep the source-of-truth generator, the package script, and the matching verification/check command aligned.
|
|
- Prefer additive generator/check pairs like `*:gen` and `*:check` over one-off undocumented scripts.
|
|
|
|
## Scope
|
|
|
|
- Keep script-runner behavior, wrapper expectations, and generated-artifact guidance here.
|
|
- Leave repo-global verification policy in the root `AGENTS.md`.
|