wenlan / scripts
AGENTS.md358 starsChanged 4 months agoApache-2.0View on GitHub
Release, sidecar, and repo-inventory contracts. These scripts are part of packaging behavior, not generic local helpers. - Sidecars always come from a backend checkout, found by resolve-backend-dir.sh (the current checkout by default, or WENLAN_BACKEND_DIR; a sibling checkout is only a legacy fallback). See docs/history.md for the retired pinned-download mode. - prepare-tauri-build-sidecars.sh is the Tauri hook; keep it aligned with app/tauri.conf.json beforeBuildCommand. - Stage only the three Wenlan executables declared by Tauri externalBin. Native reverse transport must not reintroduce a cloudflared…
1 other project uses a version of this.
Adopted by
Most recently taken up by
- wenlan-app/wenlanword for word, first seen Oct 13, 2026
Other versions1 project uses a version of this.
Word for word · 1
- wenlan-app/wenlan★ 351100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- app/AGENTS.mdAGENTS.md
- e2e/AGENTS.mdAGENTS.md
- preview/AGENTS.mdAGENTS.md
- src/AGENTS.mdAGENTS.md
- app/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- e2e/CLAUDE.mdCLAUDE.md
- preview/CLAUDE.mdCLAUDE.md
- scripts/CLAUDE.mdCLAUDE.md
- src/CLAUDE.mdCLAUDE.md
- proveSkill
- run-wenlan-appSkill
- run-wenlanSkill
- verifySkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 34
Update scripts, tests, and workflows together when release or sidecar behavior changes.
- Very specific: line 37
Every probe in lib/host-process.sh is TRI-STATE — measured / negative /
- Distinctive: line 138
Do not let CI placeholder binaries become a release substitute.
- Very specific: line 139
Do not make resolve-backend-dir.sh silently accept a directory that lacks crates/wenlan-server, crates/wenlan-mcp, and crates/wenlan-cli.
- Very specific: line 141
Do not let an awk program in a measurement pipeline exit on its first match, and do not write … | head -1.
- Very specific: line 147
Do not assume a column index when parsing ps -W, netstat -ano, or tasklist.
- Very specific: line 159
Do not write a second parse of ps -W.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md - scripts/
OVERVIEW
Release, sidecar, and repo-inventory contracts. These scripts are part of packaging behavior, not generic local helpers.
WHERE TO LOOK
| Task | Location | Notes |
| Stage sidecars | prepare-sidecars.sh | tree-build only; compiles from the checked-out backend |
| Tauri build hook | prepare-tauri-build-sidecars.sh | picks debug vs release based on TAURI_ENV_DEBUG |
| Resolve backend checkout | resolve-backend-dir.sh | validates the current checkout, or WENLAN_BACKEND_DIR; a sibling checkout is only a legacy fallback |
| Isolated dev runtime | dev-runtime.sh, dev-all.sh | worktree-owned daemon/UI ports, data dir, debug MCP socket, PID, and teardown |
| Host process primitives | lib/host-process.sh | sourced by dev-runtime.sh and both smokes; tri-state port/liveness/image probes, path spelling, identity-checked kill |
| Evidence wrapper | attest.sh | portable replacement for the personal ~/.claude/bin/attest.sh; appends to .claude/attest.jsonl and fails when it cannot |
| Negative controls | negative-controls/ | each reverts one half of a shipped remedy and FAILS if the defending suite stays green; see its README |
| Surface smokes | smoke-cli.sh, smoke-mcp.sh | isolated port + data dir + pages dir; asserted teardown; exact ledger multiset |
| Version lockstep | release-version-sync.test.ts | app, Cargo, Tauri versions must match |
| Sidecar tests | prepare-sidecars.test.ts | locks target paths and the three Wenlan sidecars |
| API route inventory | refactor/api-route-diff.mjs | route coverage signal, not a product requirement |
CONVENTIONS
- Sidecars always come from a backend checkout, found by
resolve-backend-dir.sh(the current checkout by default, orWENLAN_BACKEND_DIR; a sibling checkout is only a legacy fallback). Seedocs/history.mdfor the retired pinned-download mode. prepare-tauri-build-sidecars.shis the Tauri hook; keep it aligned withapp/tauri.conf.jsonbeforeBuildCommand.- Stage only the three Wenlan executables declared by Tauri
externalBin. Native reverse transport must not reintroduce acloudflareddependency. - Update scripts, tests, and workflows together when release or sidecar behavior changes. The workflow comments are part of the operational contract.
- Every probe in
lib/host-process.shis TRI-STATE — measured / negative / could not measure — and every caller branches on all three. A port check that cannot run must FAIL, exactly aslsof's absence used to; it must never read as "port free". Same for liveness ("could not measure" is not "dead", and must never delete an ownership record) and for the image lookup ("could not measure" is not "a different binary"). Capture the status asout="$(f)" || rc=$?: underset -e,out="$(f)"; rc=$?aborts at the assignment, andif out="$(f)"; then …; fi; rc=$?reads the compound's own status, which is 0. - An exit status is only a measurement when the tool has a status per outcome.
lsofreturns 1 both for "nothing matched" and for "an error was detected", solsof … || hit=""reports a broken probe as a free port.-tputs only pids on stdout, so the POSIX branch merges stderr in (-wfirst, to drop the benigncan't stat()warnings) and reads silence-with-1 as the negative and any text as unmeasured. Check the same way before trusting any other tool's nonzero status.kill -0is the same shape and reads as if it were not: status 1 is ESRCH and EPERM, sokill -0 "$pid" 2>/dev/nullcalls a live process this user may not signal "gone". Only the errno TEXT separates them, which is whaterrno_says_no_such_processreads; it is stillkill -0underneath, so unlikeprocess_is_aliveit keeps answering about the MSYS pid$$records rather than about a WINPID. dev-runtime.sh'sread_owned_pidis tri-state for the same reason and is read the same way:0a record,1no record,2a record that could not be read. Only2keepsclear_owned_stateaway from a record whose daemon may still be running, so folding it into1deletes the ownership of a live process and then reads its port as free. The record's data-dir member is the only optional one, which makes it the one place a dropped read status is invisible: absent and unreadable are both the empty string unless thesedstatus is checked.lock_owner_file_appearedis the one probe here with FOUR statuses, and the fourth is not decoration:0an owner appeared,1the lock DIRECTORY went away while waiting,2the directory could not be read,3the lock is still there and still names nobody. 1 and 3 were one status, and the caller refused on both — while the source comment promised 1 would go round again and letmkdirarbitrate. A lock that was released mid-wait is not an unattributable lock; a lock that is still standing with no owner in it is, and recovering THAT is how two commands come to share a lock directory. When a fourth answer exists, spell it; folding it into a neighbour is the same defect as folding "could not measure" into "no".dev-runtime.sh's LAST line on stderr isDEV_RUNTIME_RESULT: <kind>, with<kind>one ofok,safety-refusal,build-failure,staging-failure,health-failure,port-conflict,interrupted,unknown.build-failureis cargo;staging-failureis everything after it succeeded (the held DLL, the unverifiable stage) and calls for a different remedy, so a caller that retries the build must not see one for the other.interruptedis a signal and is the only failing kind a supervisor may re-run unchanged. It is a consumed contract: another lane classifies by that spelling, so do not reword, translate, add or drop a kind without changing the consumer. It is additive — every human line above it is unchanged — and it is printed from an EXIT trap so the file-scope guards, aset -eabort and a signal all carry one. The trap is installed FIRST, beforeSCRIPT_DIR,REPO_ROOTand the librarysource: each of those is a way out underset -e, and a way out that precedes the trap prints no marker at all. For the same reason a failed release must not abort the trap before the marker is printed — but ROUND 4 is that it must not be DISCARDED either, andrelease_runtime_lock || truewas the wrong remedy for a reason that has nothing to do with the trap: the collapse was INSIDE the function, whose[[ -f ]]andsedfailures each returned 0, so the|| truenever saw a status to throw away. The release now reports, and the trap reads it with a checkedif !— which suspends errexit exactly as|| truedid AND keeps the answer. A run that finished but left its lock standing makes the NEXT command refuse on a lock this one called released, so an otherwise-okrun is downgraded and exits non-zero.unknownis a REFUSAL, not a pass: it is what this prints when it cannot tell which kind applies, and a consumer must treat it the way it treatssafety-refusal. Never guess a kind.- The same rule governs
attest.sh: an unrecorded run must never be indistinguishable from a recorded one. The weekly sweep reads a missing ledger row as "the smoke never ran", so a passing command whose ledger write failed exits non-zero. Command status wins when non-zero; the ledger's status otherwise. - A tri-state is only tri-state as far as its result travels, and a witness only
counts if it CO-VARIES with the claim it ratifies. Two rules for the first-run
Windows probes, and both were found by review after the tri-state landed:
Stop-Daemoncomputed three states, printed them and returned success, so every caller saw one; it returns the state now and both call sites record a row. AndGet-ProcessTableWitnesschecked "is this a process table" (pid 4, ten rows) to ratify "wenlan-server is not in it" — so a targeted read could throw its absence error while the whole-table read CONTAINED the process, and the negative was ratified anyway. The witness is told what it is covering; the listener probe cross-checks its table-derived negative with a targeted read for the same reason, which closes the truncated-table residual on the PowerShell side thatnetstatstill has on the POSIX side. Disagreement between two reads is "could not measure", never the negative. - Where a probe's negative depends on a timing constant, the constant is a
measurement and the control must observe it. A refused loopback connect takes
~2.05 s on Windows (the SYN is retried), so
-TimeoutSec 2turned every genuine refusal into a Timeout and the negative became unreachable in principle.GAUNTLET_HEALTH_TIMEOUT_SECraises the 5 s default for a slower runner and is floored at it; below the floor the probe cannot return its own negative, which is the defect, not a tuning choice.
ANTI-PATTERNS
- Do not let CI placeholder binaries become a release substitute.
- Do not make
resolve-backend-dir.shsilently accept a directory that lackscrates/wenlan-server,crates/wenlan-mcp, andcrates/wenlan-cli. - Do not let an awk program in a measurement pipeline
exiton its first match, and do not write… | head -1. Underpipefaila producer that takes SIGPIPE reports 141, which is indistinguishable from a real parser failure. Set a flag and print atEND; collapse the head into onesed -n '/pat/{s///;p;q;}'. - Do not assume a column index when parsing
ps -W,netstat -ano, ortasklist. Read each index from the header, andexit 3atENDwhen the header is not the one the program parses, so the caller's|| return 2turns an unreadable table into "could not measure". Guarding rows oncol > 0instead does the opposite: every row is skipped, awk prints nothing and exits 0, and the empty result reads as a negative — no listener, no such process, nothing to reap. That substitution has now been found and fixed six times in this directory, twice inside the comment written to prevent it and once inside the negative control written to prove it could not happen.netstat's State column is localised on a non-English Windows, soLISTENINGis not a key either; the structural rule (a wildcard foreign address) is. - Do not write a second parse of
ps -W.lib/host-process.shhas one, behind two entry points —ps_w_row_for <PID|WINPID> <value>for one row andps_w_rows_matching <pattern>for every matching row — and a caller that needs a third question adds a mode there rather than a table walk of its own. There have been three copies; each time, the hardening landed on one of them and the others went on counting words. A second CALL SITE is fine, a second PARSE is the defect, andscripts/host-process.test.tscounts the places that run the command at all across the library and every script that sources it. - A parsed table is not a complete table.
tasklistandps -Ware checked for completeness, not just shape: every line must be a row,tasklistmust carry pid 4 (the System process exists on every Windows NT kernel) and at least ten rows, and stderr is merged into the snapshot so a warning riding alongside a truncated table is a refusal rather than an unnoticed gap.netstathas no must-appear socket, so its completeness rule is structural instead: both parses — the bash one inlib/host-process.shand the PowerShell one infirst-run/windows-zip.ps1'sGet-PortListenerWitness— require every non-blank line to BE a row, and require a UDP row as the END WITNESS, becausenetstat -anoprints the whole TCP table and then the whole UDP table, so a UDP row is evidence the stream got past the end of TCP. The ordering that rests on is checked rather than assumed (a TCP row after a UDP row is a refusal), and a table neither parse can account for is refused rather than read as "no listener". What remains is a hole in the MIDDLE of the TCP section, which the end witness cannot see; it is stated in both parses.
COMMANDS
bash -n scripts/prepare-sidecars.sh
bash -n scripts/prepare-tauri-build-sidecars.sh
bash -n scripts/resolve-backend-dir.sh
bash -n scripts/lib/host-process.sh
bash -n scripts/dev-runtime.sh
bash -n scripts/dev-all.sh
bash -n scripts/smoke-cli.sh
bash -n scripts/smoke-mcp.sh
bash -n scripts/attest.sh
bash scripts/prepare-sidecars.sh --print-paths
pnpm vitest run scripts/prepare-sidecars.test.ts scripts/release-version-sync.test.ts scripts/dev-runtime.test.ts scripts/host-process.test.ts scripts/attest.test.ts
# A green suite does not prove the suite would notice the bug. Before changing
# host-process.sh, dev-runtime.sh's process scan or ownership record,
# first-run/lib.ps1, first-run/port-precheck.sh, first-run/windows-zip.ps1 or
# first-run/windows-nsis.ps1 (their port, health and process-liveness probes),
# the Authenticode step in release.yml, or a drift_guard tooth, run the control
# that defends it -- no PR lane runs these negative-control harnesses,
# lib.test.ps1 or the first-run channels, so these are a pre-merge step by hand.
# Run the sweep, not the individual harnesses. Eleven separate command lines
# produce eleven separate results and no aggregate: run eight of them, read eight
# greens, and conclude the suite swept -- a partial run that looks exactly like
# a complete one. run-all.sh holds a registry, refuses a harness that exited 0
# without reaching its completion marker, refuses a marker that contradicts the
# exit status, and prints one verdict. ~50 min; the posix harness is ~26 of it.
bash scripts/negative-controls/run-all.sh
# Individual harnesses, for iterating on one control. A green here is evidence
# about that harness only -- it is not a sweep, and must not be reported as one.
python3 scripts/negative-controls/posix-probes-negative-controls.py
bash scripts/negative-controls/lib-ps1-negative-controls.sh
python3 scripts/negative-controls/authenticode-step-receipt.py
python3 scripts/negative-controls/a-drift-guard-inventory.py
python3 scripts/negative-controls/a-drift-guard-replica.py
bash scripts/negative-controls/port-precheck-controls.sh
bash scripts/negative-controls/dev-runtime-scan-controls.sh
bash scripts/negative-controls/dev-runtime-record-controls.sh
bash scripts/negative-controls/dev-runtime-stage-controls.sh
bash scripts/negative-controls/dev-runtime-lock-race-controls.sh
python3 scripts/negative-controls/windows-probes-negative-controls.py- Creating and destroying need different evidence. A name being free beforehand licenses registering it; it licenses nothing else. Ending, deleting or switching something off needs free-before and measured-present-after, so the thing being destroyed is provably the thing this run made. The scheduled task, the daemon process and the data directory have all been reached by a gate that only proved the first half.
- A witness reached only from the exception path ratifies total absence, never
the specific case.
try: probe(x) except Refused: passpasses on any refusal from any of the raise sites, so a control written that way tests that something declined, not that this construct did — seven controls in one file were spelled that way and none of them measured what its name claimed. Where a control's pass condition is an exception, the control must check which exception, by matching text that only its own rule emits. - The two Windows first-run channels must never be RUN to check a change to
them:
windows-zip.ps1andwindows-nsis.ps1eachRemove-Item -Recurse -Force%LOCALAPPDATA%\wenlan, which on a developer machine is the real memorydb, config and logs.windows-probes-negative-controls.pyextracts their probes and theCheckblocks that call them and drives those in isolation; verification of these two files is static analysis plus that harness, never execution.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

