Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/windows-paths-and-index-rebuild.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
'@rivus/estela': patch
---

Windows fixes found by running the test suites on Windows:

- Session paths reach the session reader with `/` separators, so a Claude Code session opened by path shows its subagents, and a Codex rollout or a Grok session given by path is recognized. A session opened by path gets the same trace id as when it is picked from the session list, as long as the path is spelled with the same letter case. Trace ids of Windows sessions change once with this release: a saved `#/s/<id>` link from an earlier version no longer opens its session, and the session index computes those summaries again.
- `export-atif` and `export-otlp` without `--out` skip a default file name taken by a dangling symbolic link instead of writing to the link's target.
- When several `estela` processes open a broken session index at the same time, the one rebuilding it waits for the others to close the file instead of running without the index.
3 changes: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
# LF in every checkout, Windows included: fixtures are read back by byte offset, and the formatter expects LF.
* text=auto eol=lf

# The lockfile is generated from the manifests; resolve merge conflicts by running
# `pnpm install`, not by hand.
pnpm-lock.yaml merge=text
42 changes: 42 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -95,3 +95,45 @@ jobs:
apps/e2e/playwright-report/
apps/e2e/test-results/
retention-days: 14

# The `test` job above is Linux on Node.js 26 with every check. This job runs the unit suites on macOS and Windows,
# and the smoke suite on the installed tarball on all three systems with Node.js 24 (the oldest release the CLI's
# `engines` allows) and 26. Budgets and the Playwright suite stay in `test`: their numbers are set on Linux runners.
platforms:
if: github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && !github.event.pull_request.draft)
name: ${{ matrix.os }}, Node.js ${{ matrix.node }}
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
node: ['24', '26']
exclude:
- os: ubuntu-latest
node: '26'
runs-on: ${{ matrix.os }}
timeout-minutes: 30
steps:
- uses: actions/checkout@v7
# Node.js 24 runs only the installed CLI, through ESTELA_SMOKE_NODE. The workspace toolchain needs ^26.13.1,
# which pnpm/setup installs next and puts ahead of this one on PATH.
- if: matrix.node == '24'
uses: actions/setup-node@v7
with:
node-version: 24
- if: matrix.node == '24'
shell: bash
run: echo "ESTELA_SMOKE_NODE=$(node -p process.execPath)" >> "$GITHUB_ENV"
- uses: pnpm/setup@v3
with:
runtime: node@^26.13.1
cache: true
require-lockfile: true
- name: Build Web once before the unit and smoke tests
run: pnpm --filter @rivus/estela-web run build
# The unit suites do not depend on the CLI's Node.js, so they run once per system. --no-bail and --no-sort
# report every package, including the dependents of one that failed.
- if: matrix.node == '26'
run: pnpm -r --no-bail --no-sort test
- name: CLI smoke on the installed tarball
working-directory: apps/e2e
run: pnpm run test:smoke
8 changes: 6 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -260,7 +260,7 @@ CI listens for PRs being opened, reopened, updated with new commits (`synchroniz
The `test` job runs for non-Draft PRs, including ordinary and Renovate PRs opened directly as Ready. New commits
on a Ready PR run CI automatically; they no longer require another Draft-to-Ready transition. Keep work in Draft
until local checks are finished. When a Draft PR event starts this workflow, its `test` job is skipped. GitHub
reports that skipped job as successful, but the skipped status is not validation evidence. Mark the PR Ready and confirm that the actual `test` job ran
reports that skipped job as successful, but the skipped status is not validation evidence. Mark the PR Ready and confirm that the actual `test` and `platforms` jobs ran
and passed for its current head and merge result before merging. Release PRs still return to Draft on every
version update and wait for a maintainer to mark them Ready.

Expand All @@ -278,7 +278,11 @@ The tarball smoke step then builds `@rivus/estela` with `vp pack` (`pnpm --filte
runs the other packages' `tsc --noEmit` builds), packs it, and tests the installed tarball. If another package gains
a distinct build command, add it to CI. The CLI build smoke assertions share one subprocess. The budgets step
(`node scripts/check-budgets.mjs`) then runs on that build and writes its measured-vs-budget table to the job summary;
the budgets and their reasons live in `scripts/budgets/budgets.mjs`. Dependency installation uses
the budgets and their reasons live in `scripts/budgets/budgets.mjs`. The `platforms` job runs beside `test` on the same
events: the unit suites on macOS and Windows, and the smoke suite on Linux, macOS, and Windows with the installed CLI on
Node.js 24 (through `ESTELA_SMOKE_NODE`) and 26. The budgets and the Playwright suite run in `test` only, because their
numbers are set on Linux runners. Text files check out with LF on every system (`.gitattributes`), because fixtures are
read back by byte offset. Dependency installation uses
`pnpm install --frozen-lockfile` with the committed lockfile; refresh the lockfile with `pnpm install` when dependency
inputs change. pnpm rejects versions published
less than a day ago (`minimumReleaseAge` in `pnpm-workspace.yaml`), so pick versions at least a day old when upgrading.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
npx @rivus/estela
```

Needs Node.js 24 or later. It lists the sessions of the agents on this machine and opens them in your browser. Nothing leaves your machine.
Needs Node.js 24 or later, on macOS, Linux, or Windows. It lists the sessions of the agents on this machine and opens them in your browser. Nothing leaves your machine.

## Why

Expand Down
2 changes: 1 addition & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
npx @rivus/estela
```

需要 Node.js 24 或更高版本。它列出本机 Agent 的会话,并在浏览器中打开。任何数据都不会离开本机。
需要 Node.js 24 或更高版本,支持 macOS、Linux 和 Windows。它列出本机 Agent 的会话,并在浏览器中打开。任何数据都不会离开本机。

## 用途

Expand Down
31 changes: 18 additions & 13 deletions apps/cli/src/entry/app.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { mkdtemp, readFile, rm } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { join, resolve } from 'node:path'
import process from 'node:process'
import { afterEach, describe, expect, it, vi } from 'vite-plus/test'
import pkg from '../../package.json' with { type: 'json' }
Expand Down Expand Up @@ -30,6 +30,9 @@ function capture(): { stdout: () => string; stderr: () => string } {

const FIX = 'Run estela --help for usage.\n'

/** A missing session in this system's absolute form, so its label reads the same before and after `resolve`. */
const missing = (name: string): string => resolve('/nonexistent', name)

describe('runCli', () => {
it('prints the package version', async () => {
const io = capture()
Expand Down Expand Up @@ -70,21 +73,23 @@ describe('runCli', () => {

it('reads the one token after -- as the session and rejects a second', async () => {
const io = capture()
expect(await runCli(['export-atif', '--', '/nonexistent/-weird.jsonl'])).toBe(1)
expect(io.stderr()).toContain('Could not export /nonexistent/-weird.jsonl: ')
expect(await runCli(['/nonexistent/a.jsonl', '--', '/nonexistent/b.jsonl'])).toBe(1)
expect(io.stderr()).toContain(`unexpected: \`/nonexistent/b.jsonl\`\n${FIX}`)
expect(await runCli(['export-atif', '--', missing('-weird.jsonl')])).toBe(1)
expect(io.stderr()).toContain(`Could not export ${missing('-weird.jsonl')}: `)
expect(await runCli([missing('a.jsonl'), '--', missing('b.jsonl')])).toBe(1)
expect(io.stderr()).toContain(`unexpected: \`${missing('b.jsonl')}\`\n${FIX}`)
})

it('keeps stdout free on an mcp failure: it carries only the protocol', async () => {
const io = capture()
expect(await runCli(['mcp', '/nonexistent/session.jsonl'])).toBe(1)
expect(await runCli(['mcp', missing('session.jsonl')])).toBe(1)
expect(io.stdout()).toBe('')
expect(io.stderr()).toMatch(/^Could not load \/nonexistent\/session\.jsonl: .+\nPass a canonical Estela JSON file/)
expect(io.stderr().startsWith(`Could not load ${missing('session.jsonl')}: `)).toBe(true)
expect(io.stderr()).toMatch(/: .+\nPass a canonical Estela JSON file/)
})

it('reads the session from ESTELA_PATH when the command line names none', async () => {
vi.stubEnv('ESTELA_PATH', '/nonexistent/from-env.jsonl')
const fromEnv = missing('from-env.jsonl')
vi.stubEnv('ESTELA_PATH', fromEnv)
const out = await mkdtemp(join(tmpdir(), 'estela-path-'))
try {
const io = capture()
Expand All @@ -94,14 +99,14 @@ describe('runCli', () => {
expect(await runCli(['export-atif', '--out', join(out, 'a.json')])).toBe(1)
expect(await runCli(['export-otlp', '--out', join(out, 'o.json')])).toBe(1)
for (const action of ['load', 'load', 'build', 'export', 'export']) {
expect(io.stderr()).toContain(`Could not ${action} /nonexistent/from-env.jsonl: `)
expect(io.stderr()).toContain(`Could not ${action} ${fromEnv}: `)
}
expect(io.stderr().split('/nonexistent/from-env.jsonl: ')).toHaveLength(6)
expect(io.stderr().split(`${fromEnv}: `)).toHaveLength(6)

// A session on the command line wins over ESTELA_PATH.
expect(await runCli(['export-atif', '/nonexistent/given.jsonl', '--out', join(out, 'g.json')])).toBe(1)
expect(io.stderr()).toContain('Could not export /nonexistent/given.jsonl: ')
expect(io.stderr().split('/nonexistent/from-env.jsonl: ')).toHaveLength(6)
expect(await runCli(['export-atif', missing('given.jsonl'), '--out', join(out, 'g.json')])).toBe(1)
expect(io.stderr()).toContain(`Could not export ${missing('given.jsonl')}: `)
expect(io.stderr().split(`${fromEnv}: `)).toHaveLength(6)
} finally {
await rm(out, { recursive: true, force: true })
}
Expand Down
20 changes: 20 additions & 0 deletions apps/cli/src/export/write-export.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,19 @@ export function defaultExportPath(sessionId: string, format: ExportFormat): stri
return defaultExportCandidate(sessionId, format, 1)
}

/** Whether `path` names an entry, a dangling symbolic link included. */
async function entryExists(path: string): Promise<boolean> {
try {
await lstat(path)
return true
} catch (error) {
if (errorCode(error) === 'ENOENT') {
return false
}
throw error
}
}

async function writeDefaultUnique(
sessionId: string,
format: ExportFormat,
Expand All @@ -55,6 +68,13 @@ async function writeDefaultUnique(
await mkdir(dirname(firstPath), { recursive: true })
for (let attempt = 1; attempt <= MAX_DEFAULT_ATTEMPTS; attempt += 1) {
const candidate = defaultExportCandidate(sessionId, format, attempt)
// Windows' `wx` (CREATE_NEW) follows a dangling symbolic link and creates its target; POSIX `wx`
// refuses any existing entry on its own. So an entry of any kind, a link included, is taken. On
// Windows a link created between this check and the open is still followed: that needs write
// access to the directory and the right to create symbolic links.
if (await entryExists(candidate)) {
continue
}
try {
const handle = await open(candidate, 'wx')
try {
Expand Down
1 change: 1 addition & 0 deletions apps/e2e/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
"@playwright/test": "1.65.0",
"@types/node": "catalog:",
"node-pty": "1.2.0-beta.18",
"tinyexec": "1.3.1",
"typescript": "catalog:",
"vite-plus": "catalog:",
"zod": "catalog:"
Expand Down
50 changes: 42 additions & 8 deletions apps/e2e/src/cli-process.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@ import type { SmokeContext } from './global-setup.ts'
import { spawn } from 'node:child_process'
import { existsSync, readFileSync } from 'node:fs'
import { networkInterfaces } from 'node:os'
import { join } from 'node:path'
import { delimiter, dirname, join } from 'node:path'
import process from 'node:process'
import { normalizeSpawnCommand } from 'tinyexec'
import { expect } from 'vite-plus/test'

export interface RunResult {
Expand All @@ -13,21 +14,28 @@ export interface RunResult {
stderr: string
}

/** Where a CLI run lives: its `HOME`, its `XDG_CACHE_HOME`, and the directory with the fake opener. */
/**
* Where a CLI run lives: its `HOME`, its `XDG_CACHE_HOME`, the directory with the fake opener, and
* the Node.js that runs the CLI, whose directory goes on `PATH` so `npx` and npm's bin shims use it too.
*/
export interface CliHome {
home: string
cache: string
fakeBin: string
node: string
}

/**
* The environment a user has: synthetic `HOME`, a cache dir inside the run, the fake opener first
* on `PATH`, no `NO_COLOR` / `FORCE_COLOR` / `ESTELA_*` from the caller, no agent home
* overrides (they would point the tests at real sessions), and no npm notices.
* `extra` goes on top (for example `ESTELA_REDACT=0`).
* The environment a user has: synthetic `HOME` (and `USERPROFILE`, which `os.homedir()` reads on
* Windows), a cache dir inside the run, the fake opener and then the CLI's Node.js first on
* `PATH`, no `NO_COLOR` / `FORCE_COLOR` / `ESTELA_*` from the caller, no agent home overrides (they
* would point the tests at real sessions), and no npm notices. `extra` goes on top (for example
* `ESTELA_REDACT=0`).
*/
export function smokeEnv(where: CliHome, openLog: string, extra: Record<string, string> = {}): NodeJS.ProcessEnv {
const env: NodeJS.ProcessEnv = { ...process.env }
// Windows spells it `Path`; a second `PATH` key next to it would leave the winner to key order.
const pathKey = Object.keys(env).find(key => key.toUpperCase() === 'PATH') ?? 'PATH'
for (const name of [
'NO_COLOR',
'FORCE_COLOR',
Expand All @@ -46,8 +54,9 @@ export function smokeEnv(where: CliHome, openLog: string, extra: Record<string,
return {
...env,
HOME: where.home,
USERPROFILE: where.home,
XDG_CACHE_HOME: where.cache,
PATH: `${where.fakeBin}:${process.env.PATH ?? ''}`,
[pathKey]: [where.fakeBin, dirname(where.node), env[pathKey] ?? ''].join(delimiter),
ESTELA_SMOKE_OPEN_LOG: openLog,
// A fresh HOME means a fresh npm update check; its notice would land in the output under test.
npm_config_update_notifier: 'false',
Expand All @@ -57,6 +66,16 @@ export function smokeEnv(where: CliHome, openLog: string, extra: Record<string,
}
}

/**
* Whether the fake opener sees the CLI's browser launches. On Windows DevFrame starts
* `cmd /c start`, which nothing on `PATH` can stand in for, so tests there pass {@link openArgs}
* and check the printed URL only.
*/
export const fakeOpener = process.platform !== 'win32'

/** `--no-open` where the fake opener cannot catch the launch, so a test never starts a real browser. */
export const openArgs: readonly string[] = fakeOpener ? [] : ['--no-open']

/** URLs the fake opener recorded, in order. */
export function openedUrls(openLog: string): string[] {
if (!existsSync(openLog)) {
Expand All @@ -67,6 +86,11 @@ export function openedUrls(openLog: string): string[] {
.filter(line => line.length > 0)
}

/** The fake opener recorded a URL, or cannot record one on this system. */
export function openSeen(openLog: string): boolean {
return !fakeOpener || openedUrls(openLog).length > 0
}

export function openLogPath(ctx: SmokeContext, name: string): string {
return join(ctx.root, `opened-${name}.log`)
}
Expand All @@ -85,13 +109,23 @@ function collect(child: ChildProcess): () => { stdout: string; stderr: string }
return () => ({ stdout, stderr })
}

/**
* Runs `command` to its exit with exactly `options.env`. `normalizeSpawnCommand` turns a Windows
* `.cmd` shim such as `npx` into a `cmd.exe` call with escaped arguments and leaves other commands
* as they are; tinyexec's `x()` is not used here because it merges `process.env` back in.
*/
export function run(
command: string,
args: string[],
options: { cwd: string; env: NodeJS.ProcessEnv },
): Promise<RunResult> {
return new Promise((resolve, reject) => {
const child = spawn(command, args, { cwd: options.cwd, env: options.env, stdio: ['ignore', 'pipe', 'pipe'] })
const spawnable = normalizeSpawnCommand(command, args, {
cwd: options.cwd,
env: options.env,
stdio: ['ignore', 'pipe', 'pipe'],
})
const child = spawn(spawnable.command, spawnable.args, spawnable.options)
const out = collect(child)
child.on('error', reject)
child.on('close', code => resolve({ code: code ?? 1, ...out() }))
Expand Down
Loading
Loading