[Bug]: npm test cannot pass on a Windows checkout of 2.0.0-beta-dev (api-docs gate blocks, then 3 tests fail)

[Hotragn]

Affected component

Build, CI, or tooling

What happened?

npm test cannot pass on a fresh Windows clone of 2.0.0-beta-dev (a25f488). It stops at the second gate, and once that is unblocked three tests fail. None of the causes are in product code — they are line-ending, symlink, and platform assumptions inside the repo's own checks — so the Linux CI runner cannot see any of them and they only ever hit contributors.

Environment: Windows 11, Node 24, default Git for Windows settings (core.autocrlf=true, core.symlinks=false).

npm test
-> Error: skills/ego-browser/references/api.md is stale; run npm run generate:api-docs

That message is a dead end: the file is not stale. Regenerating rewrites byte-identical content, git diff stays empty, and the next checkout restores CRLF.

After working around that gate, the suite runs and 3 tests fail deterministically:

330 tests, 327 pass, 3 fail
  ✖ project Agent and Codex entries share the canonical Skill
      EINVAL: invalid argument, readlink '...\.agents\skills\ego-browser'
  ✖ the direct CLI prints an ordinary uncaught error once
      Expected values to be strictly equal: undefined !== 1
  ✖ Page keyboard press and type use the addressed target session
      Meta+A must retain the native selectAll editing command

Root causes

1. scripts/generate-api-reference.mjs — --check compares representation, not content

It compares the generated markdown (always LF, written via writeFile(..., "utf8")) against the working-copy file with !==. Git for Windows checks api.md out as CRLF — measured on this branch: 96 CRLF, 0 bare LF — so the strings differ while the content is identical.

2. scripts/check-skill-translation.mjs — same defect, one step later (currently dormant)

It sha256s the raw bytes of SKILL.md, so a CRLF checkout digests differently from the LF digest recorded in the translation. Measured on this branch: worktree 7109fd54… vs LF-normalized cc00450d…. This gate exits 0 early today because skills/ego-browser/workbench/SKILL.zh.v2.md is not on the branch, so it is latent rather than live — it breaks the moment that file lands.

3. src/skill-package.test.mjs — readlink() on a non-symlink

Git for Windows materializes .agents/skills/ego-browser and .codex/skills/ego-browser as regular files containing the target path (core.symlinks=false is the default without Developer Mode), and readlink() then throws EINVAL.

4. src/run-output-sink.test.mjs — URL.pathname is not a filesystem path

The spawned entry path comes from URL.pathname, which keeps percent-encoding and the leading slash of a Windows drive path, so spawnSync never launches the bundle (status: undefined, hence undefined !== 1). Note this one is not Windows-only: pathname percent-encodes spaces, so the test also fails on macOS or Linux in any checkout whose path contains a space.

5. src/page-model.test.mjs — a test inherits the host platform

"Page keyboard press and type use the addressed target session" asserts Meta+A yields the native selectAll command and modifiers === 4. editingCommandsForKey() deliberately emits that only when the platform is darwin, and this test does not pin the platform, so it fails off macOS. The source is correct here — roughly ten sibling tests in the same file already pass { platform: "darwin" } through the existing taskForRound seam; this one just omits it.

Also observed (not part of the above)

• npm run style:check reports 112 files on a Windows checkout, because Prettier's default endOfLine: "lf" flags every CRLF file. The natural fix is a repo-wide .gitattributes, which is what fix(ego-browser): make the repo build, test, and commit on Windows #148 already proposes for the dev line — I have deliberately not duplicated that.
• Two delayed-popup tests are flaky, independent of platform: background target discovery adopts a delayed popup and reports its opener and using a delayed popup suppresses its notice before round output. Three identical runs of just those two gave fail/fail, fail/fail, pass/pass. waitForLedgerTarget() budgets 50 attempts × 2 ms rather than a wall-clock deadline, which is my guess at the cause. Happy to open that separately if useful.

Fix

I have the fix ready and verified — 38 lines across 5 files, no product code, no .gitattributes:

https://github.com/Hotragn/ego-lite/tree/beta/api-docs-crlf (branched from a25f488)

• both check scripts compare content with line endings normalized;
• the symlink test reads whichever form the checkout produced, so it still proves the entry points at ../../skills/ego-browser;
• the CLI test uses fileURLToPath();
• the keyboard test pins { platform: "darwin" } using the file's own existing seam.

Result on Windows: 330 tests, 328 pass, 2 fail, the 2 being only the pre-existing popup flake above. Linux behavior is unchanged by construction — on an LF checkout the normalization is a no-op, lstat().isSymbolicLink() still takes the readlink branch, fileURLToPath() returns what pathname did for space-free paths, and the keyboard test now pins the platform it was already assuming.

I could not open a PR for this: 2.0.0-beta-dev rejects pull requests from forks (CreatePullRequest is refused for that base, while the same account opens PRs against dev normally), and these files exist on no other branch. Tell me where you would like it and I will send it there, or cherry-pick the branch directly — whichever is less work for you.

Before submitting

• I searched the existing issues and did not find a duplicate.
• I removed secrets and sensitive data.

[Hotragn]

Re-verified against today's head, be48d11 (feat(ego-browser): compact snapshot output): still reproduces. npm run check:api-docs fails on a fresh Windows checkout for the same LF-vs-CRLF reason, so npm test still cannot get past its second gate there.

The fix branch is rebased onto be48d11 and re-run: 393 tests, 392 pass, 1 fail — the single failure is the pre-existing delayed-popup flake described above, not a regression.

https://github.com/Hotragn/ego-lite/tree/beta/api-docs-crlf

I will keep it rebased as the branch moves. Two smaller Windows-relevant branches are also current against be48d11 if they are useful to you — beta/agent-workspace (the agentWorkspace() fallback from #223, 8/8) and beta/cli-input-v2 (the CLI input forms from #226, 10/10). No action needed from me until you say where you would like any of this.

[Hotragn]

Status refresh against 82b76c9, and one of these is now fixed upstream.

Fixed — item 5. 5877a3e (fix(ego-browser): pin keyboard test platform, @section9-lab) pins { platform: "darwin" } on the Meta+A test, which is exactly the fix this issue described. I have dropped that hunk from my branch and taken the upstream wording; nothing further is needed there. Thanks for picking it up.

Still reproducing on 82b76c9 — items 1 to 4, re-checked in the tree just now rather than assumed:

#	Where	Current state
1	scripts/generate-api-reference.mjs:25	still if (actual !== expected) — LF generated vs CRLF working copy, so npm test still stops here on Windows
2	scripts/check-skill-translation.mjs:22	still readFile(canonicalPath) with no encoding, so the sha256 is over CRLF bytes (latent until the workbench translation lands)
3	src/skill-package.test.mjs:28	still a bare readlink(...), which is EINVAL where Git materializes the symlink as a file
4	src/run-output-sink.test.mjs:324	still spawnSync(process.execPath, [entry.pathname]) — also breaks on any OS if the checkout path has a space

Item 1 is the one that actually blocks: it is the second gate in npm test, and its message (api.md is stale; run npm run generate:api-docs) sends a Windows contributor down a dead end, because regenerating produces byte-identical content and git diff stays empty.

Branch refreshed onto 82b76c9, now 4 files / 34 lines:
https://github.com/Hotragn/ego-lite/tree/beta/api-docs-crlf

npm test -> 412 tests, 412 pass, 0 fail

(The delayed-popup flake I mentioned earlier passed on this run too; it is intermittent rather than fixed, and it is unrelated to these changes.)

Given #203 mentions a Windows version launching soon, item 1 seems worth taking before that lands — Windows users arriving means Windows contributors arriving, and step 2 of CONTRIBUTING currently fails for all of them. I will keep the branch rebased either way.