Skip to content

ci: run the unit and smoke suites on macOS and Windows - #144

Merged
PerfectPan merged 9 commits into
mainfrom
ci/macos-windows
Nov 17, 2026
Merged

PerfectPan merged 9 commits into
mainfrom
ci/macos-windows

Conversation

@PerfectPan

@PerfectPan PerfectPan commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Summary

Closes #92. CI now runs on macOS and Windows as well as Linux, and the smoke suite runs the CLI on Node.js 24, the oldest release its engines allows. Running the suites on Windows turned up three product bugs, fixed here.

  • CI (.github/workflows/ci.yml): a new platforms matrix job runs beside test on the same events. It runs every package's unit suite on macOS and Windows (pnpm -r --no-bail --no-sort test, so a failed package does not skip its dependents). It also runs the smoke suite on the installed tarball on Linux, macOS, and Windows, with the CLI on Node.js 24 and 26. Linux on 26 stays in test. Node.js 24 runs only the installed CLI, through ESTELA_SMOKE_NODE; the workspace toolchain stays on ^26.13.1. The budgets and the Playwright suite stay in test, because their numbers are set on Linux runners.
  • Line endings (.gitattributes): * text=auto eol=lf. Windows runners check out with autocrlf, and fixtures are read back by byte offset.
  • Windows: session paths (packages/server): the kit joins and splits session paths on / only (Claude Code subagent directories, Codex rollout names, Grok session directories). A path with \ therefore lost its subagents and its Codex or Grok detection. It also got a different trace id than the same file found by discovery, which yields the home directory's \ followed by the kit's /. toKitPath (/ on Windows, unchanged elsewhere) is now applied at the server's two entries to the kit, loadSession and summarizeRow, so every caller is covered: the CLI, MCP, and a later DSH plugin. traceIdOf hashes that form. POSIX ids are unchanged; the pinned ids in session-target.test.ts still hold. The kit's redaction already matches both separator spellings of a Windows home.
  • Windows: default export name (apps/cli/src/export/write-export.ts): Windows' wx (CREATE_NEW) follows a dangling symbolic link and creates its target. export-atif and export-otlp without --out now treat any existing entry, a link included, as a taken name. On POSIX wx already refused it.
  • Windows: session index rebuild (packages/runtime-node): Windows refuses to delete a file another process has open. When several processes opened a broken index at once, the rebuilding process got EPERM and ran without the index. On Windows that error is now retried like the busy and I/O errors, until the open's 5 s deadline.
  • Smoke harness (apps/e2e):
    • pnpm and npm run through tinyexec, which handles Windows .cmd shims. run() uses tinyexec's normalizeSpawnCommand but not x(), because x() merges process.env back into the child environment and the smoke environment removes variables on purpose.
    • On Windows the tests run the package's bin file, because npm links .cmd, .ps1, and shell shims there.
    • USERPROFILE is set next to HOME. The CLI's Node.js directory goes on PATH after the fake opener, so npx runs on it too.
    • Windows has no stand-in for DevFrame's cmd /c start, so the tests that check the opened URL pass --no-open there and check the printed URL only; the port-fallback test passes --no-open everywhere.
    • The OSC 8 check runs on POSIX only, because node-pty sets TERM from name on POSIX only.
  • Unit tests:
    • On Windows the session index tests skip the POSIX mode checks and the read-only directory case, because chmod cannot make a directory read-only there. A new test, run on every system, checks that the index is disabled with a reason when its directory cannot be created.
    • Tests that hand paths to the kit build them in the toKitPath form, and the CLI tests use this system's absolute paths.
    • The demo trace generator writes / on every system.
  • Docs:
    • CONTRIBUTING.md: the platforms job.
    • docs/development/setup.md: the Windows opener, ESTELA_SMOKE_NODE, and the node-pty pin, which had gone stale.
    • README, its Chinese copy, and getting-started: the supported systems.
  • Changeset: @rivus/estela patch for the three Windows fixes.

Follow-up for the kit, recorded in #123: read Windows paths natively, by splitting on both separators or handing out / paths from the Node platform, so that toKitPath can go. Trace ids keep hashing the / form either way.

Validation

PR CI on the head 3074c60, 44047604319, passed every job: test (Linux, with the Playwright suite and the budgets), and platforms on ubuntu/Node 24, macos/Node 24, macos/Node 26, windows/Node 24, and windows/Node 26. The run before it, 44046926140, failed once on windows/Node 26: a catalog test removed its temp home before its lock-holding child had exited. The test now waits for that exit, as the session index test already did. The workflow_dispatch runs that showed the failures fixed here: 44035983739, 44036923678, 44042396654, 44043009782, and 44044193732.

Windows smoke log lines from the last run show the CLI on 24 and the tests on 26: node: v24.22.2 (C:\hostedtoolcache\windows\node\24.22.2\x64\node.exe), tests on v26.13.1.

Locally on macOS (Node.js 26.13.1), all passed:

  • Repository checks: gh repo-checks repository
  • Docs, file conventions, layers: node scripts/check-doc-translations.mjs, node scripts/check-conventions.mjs, node scripts/check-layers.mjs, plus node scripts/check-release-intent.mjs, node scripts/format.mjs --check, and node scripts/lint-scripts.mjs
  • PR title and description: gh repo-checks pr-title, gh repo-checks pr-body
  • Changeset for shipped changes: .changeset/windows-paths-and-index-rebuild.md (patch)
  • Lint, test, typecheck, build: pnpm lint, pnpm test, pnpm typecheck, pnpm build
  • Browser bundle: node scripts/check-browser-bundle.mjs
  • Performance and size budgets: node scripts/check-budgets.mjs. All within budget: tarball 661.5 kB of 790 kB, dist/cli.mjs 1022.2 kB of 1230 kB, large-session peak RSS 476.7 MB of 1000 MB.
  • cd apps/e2e && pnpm run test:smoke: 19 passed.

The Playwright suite (test:e2e) was not run locally; it runs in the test job, which passed. The local runs above predate the last two commits, which change only tests and comments; CI covers those commits.

Risks

  • Trace ids of Windows sessions change once. A saved #/s/<id> link from an earlier version no longer opens its session, and the index computes those summaries again. Windows was untested before; the changeset says so. Letter case still counts in a Windows trace id: c:\users and C:\Users give two ids.
  • When an older Estela that keeps the index open is still running on Windows and the layout version changed, a new process waits the open's 5 s deadline before it runs without the index. A real permission error on Windows also waits 5 s now.
  • The platforms job is not a required check, because main has no branch protection yet. Once protection is set, add its five contexts next to test.
  • On Windows one error line can name a session with both separators: the label keeps the caller's spelling and the kit's part uses / (Could not load C:\p\s.jsonl: claude-code: C:/p/s.jsonl:1: unknown format generation). Nothing parses across the two parts.
  • On Windows a dangling link created between the default export name's existence check and its open is still followed. That needs write access to the working directory and the right to create symbolic links. The explicit --out path already had the same window there, because O_NOFOLLOW is 0 on Windows.
  • Agent home locations on Windows are covered by synthetic homes only, not real agent installs. Whether ConPTY passes OSC 8 links through is unchecked.

PerfectPan and others added 7 commits November 17, 2026 15:05
Adds a platforms job: unit suites on macOS and Windows, and the smoke
suite on the installed tarball on Linux, macOS and Windows with Node.js
24 and 26. The smoke harness starts npm and npx through tinyexec's
Windows shim handling, runs the installed bin file where npm links .cmd
shims, sets USERPROFILE next to HOME, and takes the CLI's Node.js from
ESTELA_SMOKE_NODE. Text files check out with LF everywhere.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Windows has no stand-in for DevFrame's cmd /c start, so the smoke tests
pass --no-open there and check the printed URL only; node-pty rejects a
signal name there. The session index tests compare platform paths and
check POSIX modes on POSIX only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… index rebuild

The kit joins and splits session paths on / only, so a path typed with
backslashes lost its Claude Code subagents and its Codex or Grok
detection, and got a different trace id than the same file found by
discovery. The CLI now hands the kit / separators on Windows, and trace
ids hash that form. A Windows rebuild whose delete hits a file another
process still has open now opens again instead of giving up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…only

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n Windows

loadSession and the catalog's summary pass now apply toKitPath, so every
caller (the CLI, the server's tests, a future plugin) gets the kit's path
form; the CLI keeps plain resolve(). The conformance tests build their
paths in that form, the demo generator writes / on every system, and the
platforms job runs every package's unit suite with --no-sort.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Windows' CREATE_NEW follows a dangling symbolic link, so the default
export name allocation now treats any existing entry as taken. Also from
review: the port-fallback smoke test passes --no-open, the CLI's Node.js
directory goes on PATH so npx runs on it, a cross-platform disabled-index
test, and the tests expect the kit path form and this system's absolute
paths. Comments and the changeset state the Windows trace id change and
the cost of the rebuild retry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PerfectPan and others added 2 commits November 17, 2026 16:27
…atalog case everywhere

From the follow-up review: the session view tests hand loadSession and
summarizeRow this system's paths, the catalog's no-index case uses a file
in place of the cache directory instead of chmod, the Playwright harness
starts the CLI on ctx.node, and the export comment names the window left
between the existence check and the open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@PerfectPan

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai

coderabbitai Bot commented Nov 17, 2026

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The changes normalize Windows session paths for loading, summaries, trace IDs, and generated traces. The session index retries Windows file-in-use errors during rebuilds, and default export filenames skip existing entries such as dangling symbolic links. The E2E harness and installed CLI tests now support platform-specific execution. A new CI matrix covers macOS, Linux, and Windows with Node.js 24 and 26, with unit suites on Node.js 26 entries.

Merge Risk: Minimal · up to 3074c

This change improves Windows path handling, index rebuild recovery and export naming, and adds cross-platform CI coverage. No actionable merge-blocking issues remain after review.

Security architecture risk: Minimal · up to 3074c

The inspected changes do not establish a material weakening of access controls, failure containment, or state ownership. Windows saved session links intentionally change, but session files remain intact and the cache can be repopulated. Index retries retain a bounded wait and an uncached fallback.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The identity change merges separator spellings of the same ordinary Windows path, not different agents or sessions within a shared file. Trace identifiers remain lookup keys rather than encoded filesystem authority. The inspected change does not establish access to an unregistered path merely by supplying an identifier.

Trust Boundaries and Controls

  • observed — Normalization occurs before the existing hardened session platform is used. Canonical-file size and schema checks remain in the load path, and the platform wrapper retains bounded Zstandard decompression and defensive read-only SQLite pragmas. Normalization itself is separator conversion, not path confinement or an authorization check.
  • observed — Default export creation now checks filesystem entries with lstat and skips an already-present dangling symlink before exclusive creation. The source explicitly retains a Windows concurrent-link race requiring directory-write and symbolic-link creation authority; the new check narrows the pre-existing behavior rather than introducing that exposure.
Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title "ci: run the unit and smoke suites on macOS and Windows" follows the type(scope): summary format and matches the main change. The PR adds a platforms CI job that runs unit and smoke suites…
Description check Passed The description follows the template. It has a Summary section that links issue #92 and explains the CI, line-ending, Windows fix, smoke harness, test, and docs changes. It has a Validation section wi…
Linked Issues check Passed [#92] The directly linked issue requires (1) a CI matrix for Linux, macOS, and Windows, (2) Node.js 24 and 26 for the packed tarball smoke suite, (3) fixes for Windows issues found by testing, and (4)…
Out of Scope Changes check Passed Every changed area maps to #92 or to its supporting work:
- CI and line endings: the platforms matrix and .gitattributes (#92 CI matrix).
- Windows product fixes: toKitPath and traceIdOf in se…
Full details: Title check

Explanation

The title "ci: run the unit and smoke suites on macOS and Windows" follows the type(scope): summary format and matches the main change. The PR adds a platforms CI job that runs unit and smoke suites on macOS and Windows. The title omits the Windows bug fixes, line-ending change, and harness work, which are secondary to the main CI change.

Full details: Description check

Explanation

The description follows the template. It has a Summary section that links issue #92 and explains the CI, line-ending, Windows fix, smoke harness, test, and docs changes. It has a Validation section with CI run links, local macOS results, and the Playwright suite skip with its reason. It has a Risks section covering trace ID changes, the 5 s index wait, the non-required status of the platforms job, and the dangling-link race. The description does not mention the optional changeset checkbox state beyond listing the changeset file, and it lists a changeset under Validation. Overall it is mostly complete.

Full details: Linked Issues check

Explanation

[#92] The directly linked issue requires (1) a CI matrix for Linux, macOS, and Windows, (2) Node.js 24 and 26 for the packed tarball smoke suite, (3) fixes for Windows issues found by testing, and (4) an acceptance criterion that smoke and unit suites pass on the three systems, or that the README names an unsupported system.

Evidence from the whole-PR summary (merge base 2533528 to head 3074c60):

  • Requirement 1 and 2: .github/workflows/ci.yml adds a platforms job. It runs the smoke suite on the installed tarball on Ubuntu, macOS, and Windows with Node.js 24 and 26. It runs unit suites on macOS and Windows. The existing test job keeps Linux on Node.js 26.
  • Requirement 3: .gitattributes (line endings), packages/server/src/sessions/session-target.ts (toKitPath, applied in load-session.ts and rows.ts), apps/cli/src/export/write-export.ts (dangling-link check), and packages/runtime-node/src/session-index-schema.ts (EPERM retry on Windows) address Windows defects. The smoke harness changes in apps/e2e cover Windows shims and environment.
  • Requirement 4: The README, its Chinese copy, and getting-started name the supported systems. The PR body reports CI run 44047604319 passed for test and all five platforms combinations. I did not verify that run directly. The unit and smoke coverage for the three systems is in the diff.

Unverified: the CI pass result depends on the PR description. The code changes do match each requirement.

Full details: Out of Scope Changes check

Explanation

Every changed area maps to #92 or to its supporting work:

  • CI and line endings: the platforms matrix and .gitattributes (#92 CI matrix).
  • Windows product fixes: toKitPath and traceIdOf in session-target code, the export default-name dangling-link check, and the session index rebuild retry. #92 asks to fix what Windows shows, and names path separators in trace ids as an expected area.
  • Smoke harness (apps/e2e): tinyexec, bin-file use on Windows, USERPROFILE, --no-open fallback, and ESTELA_SMOKE_NODE. These support running the smoke suite on Windows and Node.js 24.
  • Unit tests: adjusted for Windows, including the toKitPath form and the cache-directory test. These support the unit suites passing on Windows.
  • Docs: README, CONTRIBUTING, setup, and getting-started, which #92 requires for supported systems.
  • Changeset: a patch note for the Windows fixes.

I found no change without a connection to #92. The README and docs changes support the stated-support path. The changes to pnpm-lock.yaml are excluded and were not inspected.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@PerfectPan
PerfectPan merged commit 569b329 into main Nov 17, 2026
7 checks passed
@PerfectPan
PerfectPan deleted the ci/macos-windows branch November 17, 2026 09:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Task]: Run CI on macOS and Windows

1 participant