From d635e4c6dd4e5a625f074bfbe6524f1127da0939 Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:05:04 +0800 Subject: [PATCH 1/9] ci: run the unit and smoke suites on macOS and Windows 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 --- .gitattributes | 3 ++ .github/workflows/ci.yml | 41 +++++++++++++++++++++ apps/e2e/package.json | 1 + apps/e2e/src/cli-process.ts | 28 +++++++++++---- apps/e2e/src/cli.smoke.ts | 37 ++++++++++--------- apps/e2e/src/e2e/harness.ts | 1 + apps/e2e/src/mcp.smoke.ts | 5 ++- apps/e2e/src/picker.smoke.ts | 4 +-- apps/e2e/src/prepare-run.ts | 17 +++++++-- apps/e2e/src/tarball.ts | 69 +++++++++++++++++------------------- pnpm-lock.yaml | 3 ++ 11 files changed, 138 insertions(+), 71 deletions(-) diff --git a/.gitattributes b/.gitattributes index f260cc98..4b4fee47 100644 --- a/.gitattributes +++ b/.gitattributes @@ -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 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3a69e6fb..5ba6e3fb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -95,3 +95,44 @@ 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. + - if: matrix.node == '26' + run: pnpm test + - name: CLI smoke on the installed tarball + working-directory: apps/e2e + run: pnpm run test:smoke diff --git a/apps/e2e/package.json b/apps/e2e/package.json index 6d6af495..deca2258 100644 --- a/apps/e2e/package.json +++ b/apps/e2e/package.json @@ -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:" diff --git a/apps/e2e/src/cli-process.ts b/apps/e2e/src/cli-process.ts index 267ad55c..739c9c71 100644 --- a/apps/e2e/src/cli-process.ts +++ b/apps/e2e/src/cli-process.ts @@ -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, join } from 'node:path' import process from 'node:process' +import { normalizeSpawnCommand } from 'tinyexec' import { expect } from 'vite-plus/test' export interface RunResult { @@ -21,13 +22,15 @@ export interface CliHome { } /** - * 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 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 = {}): 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', @@ -46,8 +49,9 @@ export function smokeEnv(where: CliHome, openLog: string, extra: Record { 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 { 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() })) diff --git a/apps/e2e/src/cli.smoke.ts b/apps/e2e/src/cli.smoke.ts index dc7102c4..14137fbc 100644 --- a/apps/e2e/src/cli.smoke.ts +++ b/apps/e2e/src/cli.smoke.ts @@ -105,10 +105,10 @@ describe('installed tarball', () => { it('--version names the package version, and an unknown flag fails before any session is read', async () => { const env = smokeEnv(ctx, openLogPath(ctx, 'version')) - const version = await run(process.execPath, [ctx.bin, '--version'], { cwd: ctx.installDir, env }) + const version = await run(ctx.node, [ctx.bin, '--version'], { cwd: ctx.installDir, env }) expect(version.code).toBe(0) expect(version.stdout).toBe(`estela ${cliPackage.version}\n`) - const unknown = await run(process.execPath, [ctx.bin, '--bogus', ctx.claudePlain], { cwd: ctx.installDir, env }) + const unknown = await run(ctx.node, [ctx.bin, '--bogus', ctx.claudePlain], { cwd: ctx.installDir, env }) expect(unknown.code).toBe(1) expect(unknown.stdout).toBe('') expect(unknown.stderr).toBe('unexpected: `--bogus`\nRun estela --help for usage.\n') @@ -116,7 +116,7 @@ describe('installed tarball', () => { it("S2: a session path opens that session's workspace", async () => { const log = openLogPath(ctx, 's2') - const server = start(process.execPath, [ctx.bin, ctx.claudePlain, '--port', '0'], { + const server = start(ctx.node, [ctx.bin, ctx.claudePlain, '--port', '0'], { cwd: ctx.installDir, env: smokeEnv(ctx, log), }) @@ -155,7 +155,7 @@ describe('installed tarball', () => { holders.push(holder) } } - const server = start(process.execPath, [ctx.bin, ctx.claudePlain], { + const server = start(ctx.node, [ctx.bin, ctx.claudePlain], { cwd: ctx.installDir, env: smokeEnv(ctx, openLogPath(ctx, 'port-fallback')), }) @@ -173,7 +173,7 @@ describe('installed tarball', () => { }) it('S10: mcp lists tools and reconstruct returns completeness', async () => { - const server = start(process.execPath, [ctx.bin, 'mcp', ctx.claudePlain], { + const server = start(ctx.node, [ctx.bin, 'mcp', ctx.claudePlain], { cwd: ctx.installDir, env: smokeEnv(ctx, openLogPath(ctx, 's10')), input: true, @@ -235,7 +235,7 @@ describe('installed tarball', () => { it('S15: build piped to a file writes plain lines and no home path', async () => { const outDir = join(ctx.root, 's15-report') // stdout is a pipe: like `> log.txt`, it is not a TTY. - const result = await run(process.execPath, [ctx.bin, 'build', ctx.claudePlain, '--out-dir', outDir], { + const result = await run(ctx.node, [ctx.bin, 'build', ctx.claudePlain, '--out-dir', outDir], { cwd: ctx.installDir, env: smokeEnv(ctx, openLogPath(ctx, 's15')), }) @@ -260,11 +260,10 @@ describe('installed tarball', () => { }) const port = portOf(holder) try { - const result = await run( - process.execPath, - [ctx.bin, '--host', '127.0.0.1', '--port', String(port), '--no-open'], - { cwd: ctx.installDir, env: smokeEnv(ctx, openLogPath(ctx, 'port-busy')) }, - ) + const result = await run(ctx.node, [ctx.bin, '--host', '127.0.0.1', '--port', String(port), '--no-open'], { + cwd: ctx.installDir, + env: smokeEnv(ctx, openLogPath(ctx, 'port-busy')), + }) expect(result.code).toBe(1) expect(result.stderr).toContain(`Port ${port} is already in use.`) expect(`${result.stdout}${result.stderr}`).not.toContain('DF0052') @@ -279,7 +278,7 @@ describe('installed tarball', () => { const { port } = held const log = openLogPath(ctx, 'host-v4-loopback') - const server = start(process.execPath, [ctx.bin, '--host', '127.0.0.1', '--port', String(port)], { + const server = start(ctx.node, [ctx.bin, '--host', '127.0.0.1', '--port', String(port)], { cwd: ctx.installDir, env: smokeEnv(ctx, log), }) @@ -343,7 +342,7 @@ describe('installed tarball', () => { const held = await portHeldOnIpv6Loopback() const { port } = held const log = openLogPath(ctx, 'host-v4-wildcard') - const server = start(process.execPath, [ctx.bin, '--host', '0.0.0.0', '--port', String(port)], { + const server = start(ctx.node, [ctx.bin, '--host', '0.0.0.0', '--port', String(port)], { cwd: ctx.installDir, env: smokeEnv(ctx, log), }) @@ -390,7 +389,7 @@ describe('installed tarball', () => { await new Promise(resolve => v6Probe.close(() => resolve())) const log = openLogPath(ctx, 'host-v6-loopback') - const server = start(process.execPath, [ctx.bin, '--host', '[::1]', '--port', String(port)], { + const server = start(ctx.node, [ctx.bin, '--host', '[::1]', '--port', String(port)], { cwd: ctx.installDir, env: smokeEnv(ctx, log), }) @@ -414,7 +413,7 @@ describe('installed tarball', () => { }) it('refuses --no-auth with a non-loopback --host', async () => { - const result = await run(process.execPath, [ctx.bin, '--no-auth', '--host', '0.0.0.0'], { + const result = await run(ctx.node, [ctx.bin, '--no-auth', '--host', '0.0.0.0'], { cwd: ctx.installDir, env: smokeEnv(ctx, openLogPath(ctx, 'no-auth-host')), }) @@ -428,7 +427,7 @@ describe('installed tarball', () => { const keepFile = join(nonEmptyDir, 'keep.txt') await writeFile(keepFile, 'do-not-delete', 'utf8') - const refused = await run(process.execPath, [ctx.bin, 'build', ctx.claudePlain, '--out-dir', nonEmptyDir], { + const refused = await run(ctx.node, [ctx.bin, 'build', ctx.claudePlain, '--out-dir', nonEmptyDir], { cwd: ctx.installDir, env: smokeEnv(ctx, openLogPath(ctx, 'build-nonempty')), }) @@ -437,13 +436,13 @@ describe('installed tarball', () => { expect(await readFile(keepFile, 'utf8')).toBe('do-not-delete') const reportDir = join(ctx.root, 'build-rebuild') - const first = await run(process.execPath, [ctx.bin, 'build', ctx.claudePlain, '--out-dir', reportDir], { + const first = await run(ctx.node, [ctx.bin, 'build', ctx.claudePlain, '--out-dir', reportDir], { cwd: ctx.installDir, env: smokeEnv(ctx, openLogPath(ctx, 'build-first')), }) expect(first.code, first.stderr).toBe(0) - const rebuild = await run(process.execPath, [ctx.bin, 'build', ctx.claudePlain, '--out-dir', reportDir], { + const rebuild = await run(ctx.node, [ctx.bin, 'build', ctx.claudePlain, '--out-dir', reportDir], { cwd: ctx.installDir, env: smokeEnv(ctx, openLogPath(ctx, 'build-second')), }) @@ -451,7 +450,7 @@ describe('installed tarball', () => { expect(await readdir(reportDir)).toEqual(['index.html']) const notDirChild = await run( - process.execPath, + ctx.node, [ctx.bin, 'build', ctx.claudePlain, '--out-dir', join(keepFile, 'nested')], { cwd: ctx.installDir, diff --git a/apps/e2e/src/e2e/harness.ts b/apps/e2e/src/e2e/harness.ts index cdd56b21..ac08bec3 100644 --- a/apps/e2e/src/e2e/harness.ts +++ b/apps/e2e/src/e2e/harness.ts @@ -29,6 +29,7 @@ const e2eContext = z.object({ repo: z.string(), root: z.string(), fakeBin: z.string(), + node: z.string(), tarball: z.string(), tarballBytes: z.number(), files: z.array(z.string()), diff --git a/apps/e2e/src/mcp.smoke.ts b/apps/e2e/src/mcp.smoke.ts index c7562025..f2dc8783 100644 --- a/apps/e2e/src/mcp.smoke.ts +++ b/apps/e2e/src/mcp.smoke.ts @@ -1,7 +1,6 @@ import { mkdir, writeFile } from 'node:fs/promises' import { homedir } from 'node:os' import { join } from 'node:path' -import process from 'node:process' import { afterAll, beforeAll, describe, expect, inject, it } from 'vite-plus/test' import * as z from 'zod/mini' import { expectCleanOutput, lanAddress, openLogPath, smokeEnv, start, waitFor, type Server } from './cli-process.ts' @@ -102,7 +101,7 @@ describe('mcp without a path: the session catalog', () => { ) const cache = join(ctx.root, 'mcp-cache') await mkdir(cache, { recursive: true }) - server = start(process.execPath, [ctx.bin, 'mcp'], { + server = start(ctx.node, [ctx.bin, 'mcp'], { cwd: ctx.installDir, env: smokeEnv({ home, cache, fakeBin: ctx.fakeBin }, openLogPath(ctx, 's17'), { ESTELA_REDACT: '0' }), input: true, @@ -193,7 +192,7 @@ describe('mcp over HTTP from the dev server', () => { const cache = join(ctx.root, 'mcp-http-cache') await mkdir(cache, { recursive: true }) // The wildcard bind takes connections from the LAN; the route must still refuse them. - const server = start(process.execPath, [ctx.bin, '--mcp', '--no-open', '--host', '0.0.0.0', '--port', '0'], { + const server = start(ctx.node, [ctx.bin, '--mcp', '--no-open', '--host', '0.0.0.0', '--port', '0'], { cwd: ctx.installDir, env: smokeEnv({ home, cache, fakeBin: ctx.fakeBin }, openLogPath(ctx, 'mcp-http')), }) diff --git a/apps/e2e/src/picker.smoke.ts b/apps/e2e/src/picker.smoke.ts index 50395cca..476e253a 100644 --- a/apps/e2e/src/picker.smoke.ts +++ b/apps/e2e/src/picker.smoke.ts @@ -15,7 +15,7 @@ function readyBox(raw: string): string[] { /** The trace id the CLI gives a session path, read from its plain `Ready:` line. */ async function traceIdOf(path: string): Promise { - const server = start(process.execPath, [ctx.bin, path, '--no-open', '--port', '0'], { + const server = start(ctx.node, [ctx.bin, path, '--no-open', '--port', '0'], { cwd: ctx.installDir, env: smokeEnv(ctx, openLogPath(ctx, 's16-trace-id')), }) @@ -32,7 +32,7 @@ describe('installed tarball in a terminal', () => { const subagent = join(ctx.home, '.claude/projects/app-subagent/session.jsonl') const expected = await traceIdOf(subagent) const log = openLogPath(ctx, 's16') - const term = spawnPty(process.execPath, [ctx.bin, '--pick', '--port', '0'], { + const term = spawnPty(ctx.node, [ctx.bin, '--pick', '--port', '0'], { name: 'xterm-256color', cols: 120, rows: 40, diff --git a/apps/e2e/src/prepare-run.ts b/apps/e2e/src/prepare-run.ts index 70bb7cf3..dafda9fb 100644 --- a/apps/e2e/src/prepare-run.ts +++ b/apps/e2e/src/prepare-run.ts @@ -4,6 +4,7 @@ import { tmpdir } from 'node:os' import { dirname, join } from 'node:path' import process from 'node:process' import { fileURLToPath } from 'node:url' +import { x } from 'tinyexec' import { packAndInstall } from './tarball.ts' export const repo = join(dirname(fileURLToPath(import.meta.url)), '../../..') @@ -13,9 +14,17 @@ export interface Run extends Installed { root: string /** Holds the fake `open` and `xdg-open`. */ fakeBin: string + /** + * The Node.js that runs the installed CLI: `ESTELA_SMOKE_NODE` when set (CI points it at the + * oldest supported release), else the one running the tests. + */ + node: string } -/** Records each URL the CLI opens instead of starting a browser (`open` on macOS, `xdg-open` on Linux). */ +/** + * Records each URL the CLI opens instead of starting a browser (`open` on macOS, `xdg-open` on + * Linux). Windows has no stand-in: DevFrame starts `cmd /c start` there, which `PATH` cannot replace. + */ const OPENER = '#!/bin/sh\nprintf \'%s\\n\' "$1" >> "$ESTELA_SMOKE_OPEN_LOG"\n' /** @@ -43,10 +52,12 @@ export async function prepareRun( await chmod(join(fakeBin, opener), 0o755) } const more = await extra(root) + const node = process.env.ESTELA_SMOKE_NODE ?? process.execPath + const nodeVersion = (await x(node, ['--version'], { throwOnError: true })).stdout.trim() process.stdout.write( - `node: ${process.version}\ntarball: ${installed.tarball} (${installed.tarballBytes} bytes, ${installed.files.length} files)\n`, + `node: ${nodeVersion} (${node}), tests on ${process.version}\ntarball: ${installed.tarball} (${installed.tarballBytes} bytes, ${installed.files.length} files)\n`, ) - return { context: { root, fakeBin, ...installed, ...more }, cleanup } + return { context: { root, fakeBin, node, ...installed, ...more }, cleanup } } catch (error) { await cleanup() throw error diff --git a/apps/e2e/src/tarball.ts b/apps/e2e/src/tarball.ts index 6e309ca6..725aa49e 100644 --- a/apps/e2e/src/tarball.ts +++ b/apps/e2e/src/tarball.ts @@ -1,22 +1,9 @@ -import { execFile } from 'node:child_process' -import { mkdir, stat, writeFile } from 'node:fs/promises' +import { mkdir, readFile, stat, writeFile } from 'node:fs/promises' import { join } from 'node:path' import process from 'node:process' -import { promisify } from 'node:util' +import { x } from 'tinyexec' import * as z from 'zod/mini' -const exec = promisify(execFile) - -const text = (value: unknown): string => (typeof value === 'string' ? value : '') - -/** `execFile` failures carry `stdout` and `stderr` as own properties on the thrown `Error`. */ -function execOutput(error: unknown): { stdout: string; stderr: string } { - if (!(error instanceof Error) || !('stdout' in error) || !('stderr' in error)) { - return { stdout: '', stderr: '' } - } - return { stdout: text(error.stdout), stderr: text(error.stderr) } -} - export interface Installed { tarball: string /** Bytes of the `.tgz`. */ @@ -25,44 +12,47 @@ export interface Installed { files: string[] /** Empty project the tarball is installed into. */ installDir: string - /** `node_modules/.bin/estela` inside `installDir`. */ + /** + * The installed CLI as a file `node` can run: `node_modules/.bin/estela` inside `installDir`, + * except on Windows, where npm links bins as `.cmd`, `.ps1`, and shell shims, so this is the + * package's own bin file there. + */ bin: string /** The repository's npm registry, for npm and npx calls, which do not read `pnpm-workspace.yaml`. */ registry: string } /** - * Builds `@rivus/estela` and the workspace packages it depends on, so the tarball never - * holds a stale bundle. + * Runs a package manager command and returns its stdout; a non-zero exit throws with the tail of + * both streams. tinyexec resolves Windows `.cmd` shims (npm, npx, a pnpm installed through npm), + * which `execFile` cannot start without a shell. */ -async function buildCli(repo: string): Promise { - try { - await exec('pnpm', ['--filter', '@rivus/estela...', 'run', 'build'], { - cwd: repo, - // Vitest sets NODE_ENV=test; the published artifact must use the production build conditions. - env: { ...process.env, NODE_ENV: 'production' }, - maxBuffer: 64 * 1024 * 1024, - }) - } catch (error) { - const { stdout, stderr } = execOutput(error) +async function sh(command: string, args: string[], options: { cwd: string; env?: NodeJS.ProcessEnv }): Promise { + const result = await x(command, args, { nodeOptions: options, nodePath: false, throwOnError: false }) + if (result.exitCode !== 0) { throw new Error( - `pnpm --filter '@rivus/estela...' run build failed:\n${stdout.slice(-4000)}${stderr.slice(-4000)}`, - { - cause: error, - }, + `${command} ${args.join(' ')} exited with ${result.exitCode}:\n${result.stdout.slice(-4000)}${result.stderr.slice(-4000)}`, ) } + return result.stdout } +const installedManifest = z.object({ bin: z.object({ estela: z.string() }) }) + /** * Build, `pnpm pack` in `apps/cli`, then `npm install ` into an empty directory under * `root`. pnpm pack, not npm pack: it rewrites the `workspace:` and `catalog:` specifiers into * real versions, which `npm install` of the tarball (and a registry publish) requires. */ export async function packAndInstall(root: string, repo: string): Promise { - await buildCli(repo) + // Builds `@rivus/estela` and the workspace packages it depends on, so the tarball never holds a stale bundle. + await sh('pnpm', ['--filter', '@rivus/estela...', 'run', 'build'], { + cwd: repo, + // Vitest sets NODE_ENV=test; the published artifact must use the production build conditions. + env: { ...process.env, NODE_ENV: 'production' }, + }) const cliDir = join(repo, 'apps/cli') - const { stdout } = await exec('pnpm', ['pack', '--json', '--pack-destination', root], { cwd: cliDir }) + const stdout = await sh('pnpm', ['pack', '--json', '--pack-destination', root], { cwd: cliDir }) const packed = z.parse( z.object({ filename: z.string(), files: z.array(z.object({ path: z.string() })) }), JSON.parse(stdout), @@ -75,16 +65,21 @@ export async function packAndInstall(root: string, repo: string): Promise file.path).toSorted(), installDir, - bin: join(installDir, 'node_modules/.bin/estela'), + bin: + process.platform === 'win32' + ? join(packageDir, manifest.bin.estela) + : join(installDir, 'node_modules/.bin/estela'), registry, } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b72d34bd..8f453927 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -266,6 +266,9 @@ importers: node-pty: specifier: 1.2.0-beta.18 version: 1.2.0-beta.18 + tinyexec: + specifier: 1.3.1 + version: 1.3.1 typescript: specifier: 'catalog:' version: 7.0.2 From 1fa927554950b85c3283441654d33925b979b89d Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:12:29 +0800 Subject: [PATCH 2/9] test: keep the smoke and session index suites green on Windows 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 --- .github/workflows/ci.yml | 4 +- apps/e2e/src/cli-process.ts | 15 +++++ apps/e2e/src/cli.smoke.ts | 58 +++++++++------- apps/e2e/src/picker.smoke.ts | 34 +++++++--- .../runtime-node/src/session-index.test.ts | 67 ++++++++++++------- 5 files changed, 119 insertions(+), 59 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5ba6e3fb..18417bfb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -130,9 +130,9 @@ jobs: 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. + # The unit suites do not depend on the CLI's Node.js, so they run once per system; --no-bail reports every package. - if: matrix.node == '26' - run: pnpm test + run: pnpm -r --no-bail test - name: CLI smoke on the installed tarball working-directory: apps/e2e run: pnpm run test:smoke diff --git a/apps/e2e/src/cli-process.ts b/apps/e2e/src/cli-process.ts index 739c9c71..39664ee6 100644 --- a/apps/e2e/src/cli-process.ts +++ b/apps/e2e/src/cli-process.ts @@ -61,6 +61,16 @@ export function smokeEnv(where: CliHome, openLog: string, extra: Record 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`) } diff --git a/apps/e2e/src/cli.smoke.ts b/apps/e2e/src/cli.smoke.ts index 14137fbc..7794199f 100644 --- a/apps/e2e/src/cli.smoke.ts +++ b/apps/e2e/src/cli.smoke.ts @@ -9,9 +9,12 @@ import * as z from 'zod/mini' import cliPackage from '../../cli/package.json' with { type: 'json' } import { expectCleanOutput, + fakeOpener, lanAddress, + openArgs, openedUrls, openLogPath, + openSeen, readyUrl, run, smokeEnv, @@ -116,23 +119,25 @@ describe('installed tarball', () => { it("S2: a session path opens that session's workspace", async () => { const log = openLogPath(ctx, 's2') - const server = start(ctx.node, [ctx.bin, ctx.claudePlain, '--port', '0'], { + const server = start(ctx.node, [ctx.bin, ctx.claudePlain, '--port', '0', ...openArgs], { cwd: ctx.installDir, env: smokeEnv(ctx, log), }) try { await waitFor( 'the Ready line and the browser opener', - () => readyUrl(server.output().stdout) !== undefined && openedUrls(log).length > 0, + () => readyUrl(server.output().stdout) !== undefined && openSeen(log), ) const ready = readyUrl(server.output().stdout) expect(server.output().stdout).toContain(`Ready: ${ready!.base}#/s/${ready!.traceId}`) - // The fragment carries DevFrame's one-time code, so the trace id rides `?s=`; the SPA moves it to `#/s/`. - const [opened] = openedUrls(log) - expect(opened).toMatch( - new RegExp(`^${ready!.base.replaceAll('/', '\\/')}\\?s=${ready!.traceId}#devframe_otp=\\w+$`), - ) - expect(openedUrls(log)).toHaveLength(1) + if (fakeOpener) { + // The fragment carries DevFrame's one-time code, so the trace id rides `?s=`; the SPA moves it to `#/s/`. + const [opened] = openedUrls(log) + expect(opened).toMatch( + new RegExp(`^${ready!.base.replaceAll('/', '\\/')}\\?s=${ready!.traceId}#devframe_otp=\\w+$`), + ) + expect(openedUrls(log)).toHaveLength(1) + } // The session index loads node:sqlite; `dist/bin.mjs` drops only its ExperimentalWarning. expect(server.output().stderr).not.toContain('ExperimentalWarning') } finally { @@ -278,7 +283,7 @@ describe('installed tarball', () => { const { port } = held const log = openLogPath(ctx, 'host-v4-loopback') - const server = start(ctx.node, [ctx.bin, '--host', '127.0.0.1', '--port', String(port)], { + const server = start(ctx.node, [ctx.bin, '--host', '127.0.0.1', '--port', String(port), ...openArgs], { cwd: ctx.installDir, env: smokeEnv(ctx, log), }) @@ -286,14 +291,16 @@ describe('installed tarball', () => { try { await waitFor( 'the 127.0.0.1 Ready line and browser open', - () => readyPattern.test(server.output().stdout) && openedUrls(log).length > 0, + () => readyPattern.test(server.output().stdout) && openSeen(log), ) const stdout = server.output().stdout expect(stdout).toContain(`http://127.0.0.1:${port}/__estela/#/`) expect(stdout).not.toContain(`http://localhost:${port}`) - const opened = openedUrls(log) - expect(opened).toHaveLength(1) - expect(opened[0]).toMatch(new RegExp(`^http://127\\.0\\.0\\.1:${port}/__estela/#devframe_otp=\\w+$`)) + if (fakeOpener) { + const opened = openedUrls(log) + expect(opened).toHaveLength(1) + expect(opened[0]).toMatch(new RegExp(`^http://127\\.0\\.0\\.1:${port}/__estela/#devframe_otp=\\w+$`)) + } const res = await fetch(`http://127.0.0.1:${port}/__estela/`) expect(res.status).toBe(200) @@ -342,20 +349,21 @@ describe('installed tarball', () => { const held = await portHeldOnIpv6Loopback() const { port } = held const log = openLogPath(ctx, 'host-v4-wildcard') - const server = start(ctx.node, [ctx.bin, '--host', '0.0.0.0', '--port', String(port)], { + const server = start(ctx.node, [ctx.bin, '--host', '0.0.0.0', '--port', String(port), ...openArgs], { cwd: ctx.installDir, env: smokeEnv(ctx, log), }) try { await waitFor( 'the 127.0.0.1 Ready line and browser open', - () => - server.output().stdout.includes(`Ready: http://127.0.0.1:${port}/__estela/#/`) && openedUrls(log).length > 0, + () => server.output().stdout.includes(`Ready: http://127.0.0.1:${port}/__estela/#/`) && openSeen(log), ) expect(server.output().stdout).not.toContain(`http://localhost:${port}`) - expect(openedUrls(log)).toEqual([ - expect.stringMatching(new RegExp(`^http://127\\.0\\.0\\.1:${port}/__estela/#devframe_otp=\\w+$`)), - ]) + if (fakeOpener) { + expect(openedUrls(log)).toEqual([ + expect.stringMatching(new RegExp(`^http://127\\.0\\.0\\.1:${port}/__estela/#devframe_otp=\\w+$`)), + ]) + } expect((await fetch(`http://127.0.0.1:${port}/__estela/`)).status).toBe(200) // The wildcard still serves the page on this machine's LAN address. const lan = lanAddress() @@ -389,7 +397,7 @@ describe('installed tarball', () => { await new Promise(resolve => v6Probe.close(() => resolve())) const log = openLogPath(ctx, 'host-v6-loopback') - const server = start(ctx.node, [ctx.bin, '--host', '[::1]', '--port', String(port)], { + const server = start(ctx.node, [ctx.bin, '--host', '[::1]', '--port', String(port), ...openArgs], { cwd: ctx.installDir, env: smokeEnv(ctx, log), }) @@ -397,12 +405,14 @@ describe('installed tarball', () => { try { await waitFor( 'the [::1] Ready line and browser open', - () => readyPattern.test(server.output().stdout) && openedUrls(log).length > 0, + () => readyPattern.test(server.output().stdout) && openSeen(log), ) expect(server.output().stdout).toContain(`http://[::1]:${port}/__estela/#/`) - const opened = openedUrls(log) - expect(opened).toHaveLength(1) - expect(opened[0]).toMatch(new RegExp(`^http://\\[::1\\]:${port}/__estela/#devframe_otp=\\w+$`)) + if (fakeOpener) { + const opened = openedUrls(log) + expect(opened).toHaveLength(1) + expect(opened[0]).toMatch(new RegExp(`^http://\\[::1\\]:${port}/__estela/#devframe_otp=\\w+$`)) + } const res = await fetch(`http://[::1]:${port}/__estela/`) expect(res.status).toBe(200) diff --git a/apps/e2e/src/picker.smoke.ts b/apps/e2e/src/picker.smoke.ts index 476e253a..9ba902d7 100644 --- a/apps/e2e/src/picker.smoke.ts +++ b/apps/e2e/src/picker.smoke.ts @@ -2,7 +2,17 @@ import { join } from 'node:path' import { stripVTControlCharacters } from 'node:util' import { spawn as spawnPty } from 'node-pty' import { describe, expect, inject, it } from 'vite-plus/test' -import { openedUrls, openLogPath, readyUrl, smokeEnv, start, waitFor } from './cli-process.ts' +import { + fakeOpener, + openArgs, + openedUrls, + openLogPath, + openSeen, + readyUrl, + smokeEnv, + start, + waitFor, +} from './cli-process.ts' const ctx = inject('smoke') @@ -32,7 +42,7 @@ describe('installed tarball in a terminal', () => { const subagent = join(ctx.home, '.claude/projects/app-subagent/session.jsonl') const expected = await traceIdOf(subagent) const log = openLogPath(ctx, 's16') - const term = spawnPty(ctx.node, [ctx.bin, '--pick', '--port', '0'], { + const term = spawnPty(ctx.node, [ctx.bin, '--pick', '--port', '0', ...openArgs], { name: 'xterm-256color', cols: 120, rows: 40, @@ -56,15 +66,14 @@ describe('installed tarball in a terminal', () => { return /Search: helper\S* \(1 match\)/.test(after) && after.includes('● Ask the helper') }) term.write('\r') - await waitFor( - 'the Ready box and the browser opener', - () => readyUrl(screen) !== undefined && openedUrls(log).length > 0, - ) + await waitFor('the Ready box and the browser opener', () => readyUrl(screen) !== undefined && openSeen(log)) const ready = readyUrl(screen) expect(ready!.traceId).toBe(expected) - const [opened] = openedUrls(log) - expect(opened).toContain(`?s=${expected}#devframe_otp=`) - expect(opened!.startsWith(ready!.base)).toBe(true) + if (fakeOpener) { + const [opened] = openedUrls(log) + expect(opened).toContain(`?s=${expected}#devframe_otp=`) + expect(opened!.startsWith(ready!.base)).toBe(true) + } // The Ready box holds the one URL, as an OSC 8 link, and every box line has one width. await waitFor('the Ready box', () => readyBox(screen).length === 3) const box = readyBox(screen) @@ -73,7 +82,12 @@ describe('installed tarball in a terminal', () => { expect(screen).toContain(`\u001B]8;;${ready!.base}#/s/${expected}\u001B\\`) expect(visible().split(`${ready!.base}#/s/${expected}`)).toHaveLength(2) } finally { - term.kill('SIGTERM') + // node-pty rejects a signal name on Windows. + if (process.platform === 'win32') { + term.kill() + } else { + term.kill('SIGTERM') + } await exited } }) diff --git a/packages/runtime-node/src/session-index.test.ts b/packages/runtime-node/src/session-index.test.ts index 5c6f98a4..1000039f 100644 --- a/packages/runtime-node/src/session-index.test.ts +++ b/packages/runtime-node/src/session-index.test.ts @@ -3,6 +3,7 @@ import { chmodSync, mkdirSync, statSync, writeFileSync } from 'node:fs' import { mkdtemp, rm } from 'node:fs/promises' import { tmpdir } from 'node:os' import { dirname, join } from 'node:path' +import process from 'node:process' import { fileURLToPath, pathToFileURL } from 'node:url' import { DatabaseSync } from 'node:sqlite' import { afterEach, describe, expect, it } from 'vite-plus/test' @@ -15,6 +16,18 @@ afterEach(async () => { await Promise.all(dirs.splice(0).map(dir => rm(dir, { recursive: true, force: true }))) }) +/** + * Windows has no POSIX permission bits: Node reports 0o666 for every file and directory, and the + * user profile's ACL is what keeps the index private there. Mode checks run on POSIX only. + */ +const posixModes = process.platform !== 'win32' + +function expectMode(path: string, mode: number): void { + if (posixModes) { + expect(statSync(path).mode & 0o777, path).toBe(mode) + } +} + async function tempDir(): Promise { const dir = await mkdtemp(join(tmpdir(), 'session-index-')) dirs.push(dir) @@ -62,9 +75,11 @@ function concurrentIndexWriter(file: string): string { describe('session index', () => { it('honors XDG_CACHE_HOME and otherwise uses ~/.cache', () => { - expect(sessionIndexFile({ XDG_CACHE_HOME: '/xdg' }, '/h/u')).toBe('/xdg/rivus-estela/index.sqlite') - expect(sessionIndexFile({ XDG_CACHE_HOME: '' }, '/h/u')).toBe('/h/u/.cache/rivus-estela/index.sqlite') - expect(sessionIndexFile({}, '/h/u')).toBe('/h/u/.cache/rivus-estela/index.sqlite') + expect(sessionIndexFile({ XDG_CACHE_HOME: '/xdg' }, '/h/u')).toBe(join('/xdg', 'rivus-estela', 'index.sqlite')) + expect(sessionIndexFile({ XDG_CACHE_HOME: '' }, '/h/u')).toBe( + join('/h/u', '.cache', 'rivus-estela', 'index.sqlite'), + ) + expect(sessionIndexFile({}, '/h/u')).toBe(join('/h/u', '.cache', 'rivus-estela', 'index.sqlite')) }) it('creates the file with mode 0600 and reopens the same summary', async () => { @@ -76,7 +91,7 @@ describe('session index', () => { expect(index.get('a', 10, 1_000)?.inputTokens).toBe(118_400) expect(index.get('a', 11, 1_000)).toBeUndefined() index.close() - expect(statSync(file).mode & 0o777).toBe(0o600) + expectMode(file, 0o600) const again = openSessionIndex({ summaryVersion: 1, file }) expect(again.get('a', 10, 1_000)?.requests).toBe(4) @@ -144,7 +159,7 @@ describe('session index', () => { const index = openSessionIndex({ summaryVersion: 1, file }) index.putSummaries([summary({ traceId: 'a', path: '/logs/a.jsonl' })]) expect(index.search('auth')).toEqual(['a']) - expect(statSync(file).mode & 0o777).toBe(0o600) + expectMode(file, 0o600) index.close() }) @@ -286,24 +301,30 @@ describe('session index', () => { it('creates the directory 0700 and the file 0600', async () => { const file = join(await tempDir(), 'cache', 'rivus-estela', 'index.sqlite') openSessionIndex({ summaryVersion: 1, file }).close() - expect(statSync(dirname(file)).mode & 0o777).toBe(0o700) - expect(statSync(file).mode & 0o777).toBe(0o600) + expect(statSync(dirname(file)).isDirectory()).toBe(true) + expect(statSync(file).isFile()).toBe(true) + expectMode(dirname(file), 0o700) + expectMode(file, 0o600) }) - it('returns a disabled index with the reason when the cache directory is not writable', async () => { - const cache = join(await tempDir(), 'cache') - mkdirSync(cache) - chmodSync(cache, 0o500) - try { - const index = openSessionIndex({ summaryVersion: 1, env: { XDG_CACHE_HOME: cache }, homeDir: '/h/u' }) - expect(index.enabled).toBe(false) - expect(index.unavailable).toMatch(/EACCES|permission/i) - expect(index.search('x')).toBeUndefined() - index.close() - } finally { - chmodSync(cache, 0o700) - } - }) + // chmod cannot make a directory read-only on Windows. + it.skipIf(!posixModes)( + 'returns a disabled index with the reason when the cache directory is not writable', + async () => { + const cache = join(await tempDir(), 'cache') + mkdirSync(cache) + chmodSync(cache, 0o500) + try { + const index = openSessionIndex({ summaryVersion: 1, env: { XDG_CACHE_HOME: cache }, homeDir: '/h/u' }) + expect(index.enabled).toBe(false) + expect(index.unavailable).toMatch(/EACCES|permission/i) + expect(index.search('x')).toBeUndefined() + index.close() + } finally { + chmodSync(cache, 0o700) + } + }, + ) it('lets several processes open a fresh cache at once', async () => { const dir = await tempDir() @@ -356,9 +377,9 @@ describe('session index', () => { const file = join(dir, 'index.sqlite') const index = openSessionIndex({ summaryVersion: 1, file }) index.putSummaries([summary({ traceId: 'a', path: '/logs/a.jsonl' })]) - expect(statSync(dir).mode & 0o777).toBe(0o700) + expectMode(dir, 0o700) for (const suffix of ['', '-wal', '-shm']) { - expect({ suffix, mode: statSync(`${file}${suffix}`).mode & 0o777 }).toEqual({ suffix, mode: 0o600 }) + expectMode(`${file}${suffix}`, 0o600) } const raw = new DatabaseSync(file) expect(raw.prepare('PRAGMA journal_mode').get()).toEqual({ journal_mode: 'wal' }) From 7d7a7ea27e1c2204ac1488ebec133c1bbbeed805 Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:54:06 +0800 Subject: [PATCH 3/9] fix: read Windows session paths in the kit's form and retry a blocked 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 --- .changeset/windows-paths-and-index-rebuild.md | 8 +++++++ CONTRIBUTING.md | 8 +++++-- apps/cli/src/entry/app.ts | 6 ++--- docs/development/setup.md | 4 ++-- .../runtime-node/src/session-index-schema.ts | 22 +++++++++++++++---- packages/server/src/index.ts | 2 +- .../src/sessions/session-target.test.ts | 17 +++++++++++++- .../server/src/sessions/session-target.ts | 14 +++++++++++- 8 files changed, 67 insertions(+), 14 deletions(-) create mode 100644 .changeset/windows-paths-and-index-rebuild.md diff --git a/.changeset/windows-paths-and-index-rebuild.md b/.changeset/windows-paths-and-index-rebuild.md new file mode 100644 index 00000000..c72c4a2b --- /dev/null +++ b/.changeset/windows-paths-and-index-rebuild.md @@ -0,0 +1,8 @@ +--- +'@rivus/estela': patch +--- + +Windows fixes found by running the test suites on Windows: + +- A session path given on the command line or in `ESTELA_PATH` is passed to the session reader with `/` separators, so a Claude Code session opened by path shows its subagents, a Codex rollout and a Grok session are recognized, and the session gets the same trace id as when it is picked from the session list. +- 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2232f4d6..5d46ba78 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. @@ -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. diff --git a/apps/cli/src/entry/app.ts b/apps/cli/src/entry/app.ts index f5118b14..7d21c611 100644 --- a/apps/cli/src/entry/app.ts +++ b/apps/cli/src/entry/app.ts @@ -6,7 +6,7 @@ import { parse, printErrors } from '@bomb.sh/router' import { homeDir } from '@rivus/estela-runtime-node' import pkg from '../../package.json' with { type: 'json' } import { demoFixturePath } from '../paths.ts' -import { parseSessionTarget } from '@rivus/estela-server' +import { parseSessionTarget, toKitPath } from '@rivus/estela-server' import type { ExportFormat } from '../export/write-export.ts' import { runBuild, type BuildInput } from './commands/build.ts' import { runDev, type DevInput } from './commands/dev.ts' @@ -26,10 +26,10 @@ function usage(detail: string): CliError { return new CliError({ kind: 'usage', detail }) } -/** The target of a session given on the command line (`path` or `path#sessionId`), its path made absolute. */ +/** The target of a session given on the command line (`path` or `path#sessionId`), its path made absolute in the kit's form. */ function commandLineTarget(input: string): SessionTarget { const target = parseSessionTarget(input) - return { ...target, path: resolve(target.path) } + return { ...target, path: toKitPath(resolve(target.path)) } } /** An empty ESTELA_PATH names no session. */ diff --git a/docs/development/setup.md b/docs/development/setup.md index 55dd16cd..543b585d 100644 --- a/docs/development/setup.md +++ b/docs/development/setup.md @@ -133,14 +133,14 @@ ATIF export ([export formats](../reference/export-formats.md)): ## CLI smoke on the installed tarball -`apps/e2e` (`@rivus/estela-e2e`, private) runs `pnpm pack` in `apps/cli`, installs the tarball into an empty temp directory, builds a synthetic `HOME` from `fixtures/sessions//conformance`, and puts a fake `open` / `xdg-open` first on `PATH` that records the URL instead of starting a browser. It covers `--help` (through `npx`), S2, S10, S17 and S18 (`mcp.smoke.ts`), S13 (Node.js 22 through `npx -y node@22`), S15, and S16 (in a pseudo-terminal through `node-pty`, pinned to `1.2.0-beta.15` because 1.1.0 ships no Linux prebuilds). It is not part of `pnpm test`, because it packs and installs. Setup first runs `pnpm --filter '@rivus/estela...' run build`, so the tarball never holds a stale bundle. +`apps/e2e` (`@rivus/estela-e2e`, private) runs `pnpm pack` in `apps/cli`, installs the tarball into an empty temp directory, builds a synthetic `HOME` (also set as `USERPROFILE`, which Windows reads) from `fixtures/sessions//conformance`, and puts a fake `open` / `xdg-open` first on `PATH` that records the URL instead of starting a browser. Windows has no such stand-in, because DevFrame opens the browser there through `cmd /c start`; the tests that check the opened URL pass `--no-open` on Windows and check the printed URL only. It covers `--help` (through `npx`), S2, S10, S17 and S18 (`mcp.smoke.ts`), S13 (Node.js 22 through `npx -y node@22`), S15, and S16 (in a pseudo-terminal through `node-pty`, pinned to `1.2.0-beta.18` because 1.1.0 ships no Linux prebuilds). It is not part of `pnpm test`, because it packs and installs. Setup first runs `pnpm --filter '@rivus/estela...' run build`, so the tarball never holds a stale bundle. ```bash cd apps/e2e pnpm run test:smoke ``` -`TMPDIR` chooses where the temp directory goes. `ESTELA_SMOKE_KEEP=1` keeps it after the run. The install step needs the npm registry. The CLI runs with npm's update notifier, fund, and audit messages off, so its output is only its own. CI runs it in the `test` job on Node.js `^26.13.1`. +`TMPDIR` chooses where the temp directory goes. `ESTELA_SMOKE_KEEP=1` keeps it after the run. `ESTELA_SMOKE_NODE=` runs the installed CLI with that Node.js while the tests run on the workspace's. The install step needs the npm registry. The CLI runs with npm's update notifier, fund, and audit messages off, so its output is only its own. CI runs it in the `test` job on Linux with Node.js `^26.13.1`, and in the `platforms` job on Linux, macOS, and Windows with the CLI on Node.js 24 and 26. ## Browser end-to-end on the installed tarball diff --git a/packages/runtime-node/src/session-index-schema.ts b/packages/runtime-node/src/session-index-schema.ts index 871b2cf5..701e9f45 100644 --- a/packages/runtime-node/src/session-index-schema.ts +++ b/packages/runtime-node/src/session-index-schema.ts @@ -1,5 +1,6 @@ import { chmodSync, closeSync, existsSync, fchmodSync, mkdirSync, openSync, rmSync, statSync } from 'node:fs' import { dirname } from 'node:path' +import process from 'node:process' import { DatabaseSync } from 'node:sqlite' import * as z from 'zod/mini' @@ -47,6 +48,7 @@ class LayoutMismatch extends Error {} const sqliteError = z.object({ errcode: z.number() }) const fileExists = z.object({ code: z.literal('EEXIST') }) +const fileInUse = z.object({ code: z.enum(['EPERM', 'EBUSY']) }) const versionRow = z.object({ user_version: z.number() }) const countRow = z.object({ n: z.number() }) @@ -83,6 +85,16 @@ export function isTransient(error: unknown): boolean { return code !== undefined && (BUSY_CODES.has(code) || code === IOERR_CODE) } +/** + * Windows refuses to delete a file that another process has open (SQLite opens it without + * `FILE_SHARE_DELETE`), so a rebuild's delete fails with EPERM or EBUSY while another opener still + * holds the broken file; that opener lets go before its next try. On POSIX these codes are real + * permission problems. + */ +function isOpenElsewhere(error: unknown): boolean { + return process.platform === 'win32' && z.safeParse(fileInUse, error).success +} + /** 0 when the pragma returns no number: `prepare` then creates the schema in an empty file or rebuilds the file. */ function readVersion(db: DatabaseSync): number { return z.safeParse(versionRow, db.prepare('PRAGMA user_version').get()).data?.user_version ?? 0 @@ -225,8 +237,9 @@ function rebuildUnderLock(file: string, lock: string): DatabaseSync | undefined * The schema is created inside `BEGIN IMMEDIATE`, so two processes opening a fresh cache at * once end with one schema. The file is rebuilt only when it is not a database, is corrupt, or * has another layout version, and only by the process holding `.lock`; the - * others wait for that lock to go and open again. A busy or I/O error from a concurrent rebuild - * is retried until the open succeeds. Throws for anything else (for example EACCES), + * others wait for that lock to go and open again. A busy or I/O error from a concurrent rebuild, + * or a Windows delete refused while another process has the file open, is retried until the open + * succeeds. Throws for anything else (for example EACCES), * or after `LOCK_WAIT_MS`; the caller runs without the index. */ export function openDatabase(file: string): DatabaseSync { @@ -250,8 +263,9 @@ export function openDatabase(file: string): DatabaseSync { return rebuilt } } catch (error) { - // The rebuild itself hit a concurrent process (busy, or I/O from its delete): open again. - if (!isTransient(error)) { + // The rebuild itself hit a concurrent process (busy, I/O from its delete, or a Windows delete + // refused while another process has the file open): open again. + if (!isTransient(error) && !isOpenElsewhere(error)) { throw error } failure = error diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts index bd5a042f..a4ea2f19 100644 --- a/packages/server/src/index.ts +++ b/packages/server/src/index.ts @@ -9,4 +9,4 @@ export type { AgentProgress, SessionCatalog } from './catalog/session-catalog.ts export { checkReportOutDir, reportOf, ReportOutDirError, writeReport } from './report/report.ts' export { loadSession, type ShellPlatform } from './sessions/load-session.ts' export { errorMessage } from './sessions/read-failure.ts' -export { oneLine, parseSessionTarget, sessionTargetLabel } from './sessions/session-target.ts' +export { oneLine, parseSessionTarget, sessionTargetLabel, toKitPath } from './sessions/session-target.ts' diff --git a/packages/server/src/sessions/session-target.test.ts b/packages/server/src/sessions/session-target.test.ts index 53165394..63b62411 100644 --- a/packages/server/src/sessions/session-target.test.ts +++ b/packages/server/src/sessions/session-target.test.ts @@ -1,5 +1,6 @@ import { describe, expect, it } from 'vite-plus/test' -import { parseSessionTarget, traceIdOf } from './session-target.ts' +import process from 'node:process' +import { parseSessionTarget, toKitPath, traceIdOf } from './session-target.ts' describe('traceIdOf', () => { // Pinned: URLs carry these ids, so a saved `#/s/` link must keep opening the same session. @@ -11,6 +12,20 @@ describe('traceIdOf', () => { '8add3d2f035cb7c5c365734c', ) }) + + it.runIf(process.platform === 'win32')('gives every separator spelling of one Windows path one id', () => { + const typed = traceIdOf({ agent: 'claude-code', path: 'C:\\Users\\me\\.claude\\projects\\p\\s.jsonl' }) + expect(traceIdOf({ agent: 'claude-code', path: 'C:\\Users\\me/.claude/projects/p/s.jsonl' })).toBe(typed) + expect(traceIdOf({ agent: 'claude-code', path: 'C:/Users/me/.claude/projects/p/s.jsonl' })).toBe(typed) + }) +}) + +describe('toKitPath', () => { + it('writes Windows separators as / and leaves other systems alone', () => { + expect(toKitPath('C:\\Users\\me/.claude\\projects', 'win32')).toBe('C:/Users/me/.claude/projects') + expect(toKitPath('/u/me/a\\b.jsonl', 'linux')).toBe('/u/me/a\\b.jsonl') + expect(toKitPath('/u/me/a\\b.jsonl', 'darwin')).toBe('/u/me/a\\b.jsonl') + }) }) describe('parseSessionTarget', () => { diff --git a/packages/server/src/sessions/session-target.ts b/packages/server/src/sessions/session-target.ts index f143bbc8..784970c1 100644 --- a/packages/server/src/sessions/session-target.ts +++ b/packages/server/src/sessions/session-target.ts @@ -1,17 +1,29 @@ import { createHash } from 'node:crypto' import { basename } from 'node:path' +import process from 'node:process' import type { SessionTarget } from '@rivus/agent-kit/transcript' +/** + * A session path as the kit reads it. The kit joins and splits session paths on `/` only (its + * Claude Code subagent directory, Codex rollout names, Grok session directories), so on Windows a + * path's `\` separators become `/`, which Node's fs also takes. Other systems keep the path as given. + */ +export function toKitPath(path: string, platform: NodeJS.Platform = process.platform): string { + return platform === 'win32' ? path.replaceAll('\\', '/') : path +} + /** * The trace id of a session: an opaque hash of agent and path, plus the session id when the path * addresses one session inside a file that holds several (the `path#id` form). The catalog turns it * back into a target. URLs and the session index hold these ids, so the hashed input must stay exactly this. + * The path is hashed in its {@link toKitPath} form: on Windows discovery yields the home directory's + * `\` followed by the kit's `/`, and a path typed on the command line has `\` only. */ export function traceIdOf(target: { agent: string; path: string; sessionId?: string }): string { return createHash('sha256') .update(target.agent) .update('\0') - .update(target.path) + .update(toKitPath(target.path)) .update('\0') .update(target.sessionId ?? '') .digest('hex') From fc8d5cadb68ca622a822a95ba249e1f400a084fc Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Tue, 17 Nov 2026 15:59:49 +0800 Subject: [PATCH 4/9] test: wait for the lock holder's exit and check OSC 8 links on POSIX only Co-Authored-By: Claude Opus 5.5 --- apps/e2e/src/picker.smoke.ts | 5 ++++- packages/runtime-node/src/session-index.test.ts | 3 +++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/apps/e2e/src/picker.smoke.ts b/apps/e2e/src/picker.smoke.ts index 9ba902d7..3557d87e 100644 --- a/apps/e2e/src/picker.smoke.ts +++ b/apps/e2e/src/picker.smoke.ts @@ -79,7 +79,10 @@ describe('installed tarball in a terminal', () => { const box = readyBox(screen) expect(new Set(box.map(line => Array.from(line).length)).size, box.join('\n')).toBe(1) expect(box[1]).toContain(`${ready!.base}#/s/${expected}`) - expect(screen).toContain(`\u001B]8;;${ready!.base}#/s/${expected}\u001B\\`) + // node-pty passes `name` as TERM on POSIX only; without TERM on Windows the CLI prints a plain URL. + if (process.platform !== 'win32') { + expect(screen).toContain(`\u001B]8;;${ready!.base}#/s/${expected}\u001B\\`) + } expect(visible().split(`${ready!.base}#/s/${expected}`)).toHaveLength(2) } finally { // node-pty rejects a signal name on Windows. diff --git a/packages/runtime-node/src/session-index.test.ts b/packages/runtime-node/src/session-index.test.ts index 1000039f..c176ccb9 100644 --- a/packages/runtime-node/src/session-index.test.ts +++ b/packages/runtime-node/src/session-index.test.ts @@ -409,6 +409,7 @@ describe('session index', () => { ], { stdio: ['ignore', 'pipe', 'inherit'] }, ) + const holderExited = new Promise(resolve => holder.once('exit', () => resolve())) await new Promise(resolve => holder.stdout.once('data', () => resolve())) const started = performance.now() const index = openSessionIndex({ summaryVersion: 1, file }) @@ -420,6 +421,8 @@ describe('session index', () => { expect(performance.now() - started).toBeLessThan(1_000) index.close() holder.kill() + // Windows keeps the holder's -wal file locked until it has exited, and the temp directory goes after the test. + await holderExited }) it('rebuilds a broken file once when several processes open it at the same time', async () => { From 1e9234280ac0c826edea89ef0c99922b977e9fb7 Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:08:22 +0800 Subject: [PATCH 5/9] fix(server): hand the kit /-separated paths at the server's entries on 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 --- .changeset/windows-paths-and-index-rebuild.md | 2 +- .github/workflows/ci.yml | 5 +- apps/cli/src/entry/app.ts | 6 +- packages/server/src/catalog/rows.ts | 14 +++-- packages/server/src/index.ts | 2 +- .../server/src/sessions/conformance.test.ts | 15 +++-- packages/server/src/sessions/load-session.ts | 9 +-- .../server/src/sessions/session-target.ts | 2 + packages/server/src/testsupport/demo-trace.ts | 11 ++-- packages/server/test/catalog-cache.test.ts | 55 +++++++++++-------- 10 files changed, 69 insertions(+), 52 deletions(-) diff --git a/.changeset/windows-paths-and-index-rebuild.md b/.changeset/windows-paths-and-index-rebuild.md index c72c4a2b..96aba3ef 100644 --- a/.changeset/windows-paths-and-index-rebuild.md +++ b/.changeset/windows-paths-and-index-rebuild.md @@ -4,5 +4,5 @@ Windows fixes found by running the test suites on Windows: -- A session path given on the command line or in `ESTELA_PATH` is passed to the session reader with `/` separators, so a Claude Code session opened by path shows its subagents, a Codex rollout and a Grok session are recognized, and the session gets the same trace id as when it is picked from the session list. +- Session paths reach the session reader with `/` separators, so a Claude Code session opened by path shows its subagents, a Codex rollout and a Grok session given by path are recognized, and a session opened by path gets the same trace id as when it is picked from the session list. - 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. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 18417bfb..24eaa4a4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -130,9 +130,10 @@ jobs: 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 reports every package. + # 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 test + run: pnpm -r --no-bail --no-sort test - name: CLI smoke on the installed tarball working-directory: apps/e2e run: pnpm run test:smoke diff --git a/apps/cli/src/entry/app.ts b/apps/cli/src/entry/app.ts index 7d21c611..f5118b14 100644 --- a/apps/cli/src/entry/app.ts +++ b/apps/cli/src/entry/app.ts @@ -6,7 +6,7 @@ import { parse, printErrors } from '@bomb.sh/router' import { homeDir } from '@rivus/estela-runtime-node' import pkg from '../../package.json' with { type: 'json' } import { demoFixturePath } from '../paths.ts' -import { parseSessionTarget, toKitPath } from '@rivus/estela-server' +import { parseSessionTarget } from '@rivus/estela-server' import type { ExportFormat } from '../export/write-export.ts' import { runBuild, type BuildInput } from './commands/build.ts' import { runDev, type DevInput } from './commands/dev.ts' @@ -26,10 +26,10 @@ function usage(detail: string): CliError { return new CliError({ kind: 'usage', detail }) } -/** The target of a session given on the command line (`path` or `path#sessionId`), its path made absolute in the kit's form. */ +/** The target of a session given on the command line (`path` or `path#sessionId`), its path made absolute. */ function commandLineTarget(input: string): SessionTarget { const target = parseSessionTarget(input) - return { ...target, path: toKitPath(resolve(target.path)) } + return { ...target, path: resolve(target.path) } } /** An empty ESTELA_PATH names no session. */ diff --git a/packages/server/src/catalog/rows.ts b/packages/server/src/catalog/rows.ts index deca2973..8309c207 100644 --- a/packages/server/src/catalog/rows.ts +++ b/packages/server/src/catalog/rows.ts @@ -8,7 +8,7 @@ import { summarizeSession } from '@rivus/agent-kit/transcript' import { redactText } from '@rivus/agent-kit/redact' import type { ShellPlatform } from '../sessions/load-session.ts' import { loadFailure } from '../sessions/read-failure.ts' -import { projectName, traceIdOf, sessionTargetLabel } from '../sessions/session-target.ts' +import { projectName, traceIdOf, sessionTargetLabel, toKitPath } from '../sessions/session-target.ts' import { sessionProviders } from '../sessions/adapters.ts' /** Server-side row. `path` never leaves the server; the browser gets `traceId`. */ @@ -88,10 +88,14 @@ export async function summarizeRow( adapters: SessionAdapters | undefined, target: SessionRef, ): Promise { - const result = await summarizeSession(platform, target, { - ...(adapters ? { providers: sessionProviders(adapters) } : {}), - prompts: { limit: PROMPT_LIMIT, maxChars: PROMPT_CHARS }, - }) + const result = await summarizeSession( + platform, + { ...target, path: toKitPath(target.path) }, + { + ...(adapters ? { providers: sessionProviders(adapters) } : {}), + prompts: { limit: PROMPT_LIMIT, maxChars: PROMPT_CHARS }, + }, + ) if (!result.ok) { return { error: loadFailure(result.error, platform.home, sessionTargetLabel(target), target.path) } } diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts index a4ea2f19..bd5a042f 100644 --- a/packages/server/src/index.ts +++ b/packages/server/src/index.ts @@ -9,4 +9,4 @@ export type { AgentProgress, SessionCatalog } from './catalog/session-catalog.ts export { checkReportOutDir, reportOf, ReportOutDirError, writeReport } from './report/report.ts' export { loadSession, type ShellPlatform } from './sessions/load-session.ts' export { errorMessage } from './sessions/read-failure.ts' -export { oneLine, parseSessionTarget, sessionTargetLabel, toKitPath } from './sessions/session-target.ts' +export { oneLine, parseSessionTarget, sessionTargetLabel } from './sessions/session-target.ts' diff --git a/packages/server/src/sessions/conformance.test.ts b/packages/server/src/sessions/conformance.test.ts index b6c94271..23f71272 100644 --- a/packages/server/src/sessions/conformance.test.ts +++ b/packages/server/src/sessions/conformance.test.ts @@ -13,23 +13,26 @@ import { } from '@rivus/agent-kit/testing' import { afterAll, describe, expect, it } from 'vite-plus/test' import { loadSession } from './load-session.ts' +import { toKitPath } from './session-target.ts' const here = dirname(fileURLToPath(import.meta.url)) const repo = join(here, '../../../..') -const fixturesOf = (agent: string): string => join(repo, 'fixtures/sessions', agent, 'conformance') +/** A path in the form the server hands the kit: the kit's conformance runner calls the adapters directly. */ +const kitJoin = (...parts: string[]): string => toKitPath(join(...parts)) +const fixturesOf = (agent: string): string => kitJoin(repo, 'fixtures/sessions', agent, 'conformance') const platform = createNodePlatform() /** Absolute paths for the session file and its side files. */ function sessionsOf(root: string, sessions: ConformanceSession[]): ConformanceSession[] { return sessions.map(session => ({ ...session, - path: join(root, session.path), - ...(session.files ? { files: session.files.map(file => join(root, file)) } : {}), + path: kitJoin(root, session.path), + ...(session.files ? { files: session.files.map(file => kitJoin(root, file)) } : {}), ...(session.recordKeys ? { recordKeys: session.recordKeys.map(key => { const at = key.indexOf('\0') - return `${join(root, key.slice(0, at))}${key.slice(at)}` + return `${kitJoin(root, key.slice(0, at))}${key.slice(at)}` }), } : {}), @@ -150,7 +153,7 @@ function oversizedOf(agent: string): SessionAdapterFixtures['oversized'] { if (line === undefined) { return undefined } - const root = mkdtempSync(join(tmpdir(), `at-conformance-${agent}-`)) + const root = toKitPath(mkdtempSync(join(tmpdir(), `at-conformance-${agent}-`))) overRoots.push(root) // The name each adapter's discover lists. const name = @@ -163,7 +166,7 @@ function oversizedOf(agent: string): SessionAdapterFixtures['oversized'] { : agent === 'gemini-cli' ? 'session-over.jsonl' : 'session.jsonl' - const file = join(root, name) + const file = kitJoin(root, name) writeFileSync(file, oversizedSession(line)) return { root, file } } diff --git a/packages/server/src/sessions/load-session.ts b/packages/server/src/sessions/load-session.ts index 7987cb25..a801b4f4 100644 --- a/packages/server/src/sessions/load-session.ts +++ b/packages/server/src/sessions/load-session.ts @@ -7,7 +7,7 @@ import { loadTranscript } from '@rivus/agent-kit/transcript' import { isTrace } from '@rivus/estela-schema' import { hardenPlatform, MAX_CANONICAL_TRACE_BYTES, MAX_CANONICAL_TRACE_MB } from './node-platform.ts' import { loadErrorMessage } from './read-failure.ts' -import { sessionTargetLabel } from './session-target.ts' +import { sessionTargetLabel, toKitPath } from './session-target.ts' import { transcriptToTrace } from './transcript-trace.ts' import { sessionProviders } from './adapters.ts' @@ -34,7 +34,8 @@ export interface LoadSessionOptions { * `No adapter accepted …`, `agent: file:line: unknown format generation`, and the * IO error's own message. */ -export async function loadSession(target: SessionTarget, options: LoadSessionOptions): Promise { +export async function loadSession(input: SessionTarget, options: LoadSessionOptions): Promise { + const target = { ...input, path: toKitPath(input.path) } const platform = hardenPlatform(options.platform) const fs = platform.fs try { @@ -42,7 +43,7 @@ export async function loadSession(target: SessionTarget, options: LoadSessionOpt const stat = await fs.stat(target.path, { followSymlinks: true }) if (stat && stat.size > MAX_CANONICAL_TRACE_BYTES) { throw new Error( - `${sessionTargetLabel(target)}: canonical trace file exceeds the ${MAX_CANONICAL_TRACE_MB} MB limit`, + `${sessionTargetLabel(input)}: canonical trace file exceeds the ${MAX_CANONICAL_TRACE_MB} MB limit`, ) } const bytes = await readRange(fs, target.path) @@ -63,7 +64,7 @@ export async function loadSession(target: SessionTarget, options: LoadSessionOpt ...(options.onProgress ? { onProgress: options.onProgress } : {}), }) if (!loaded.ok) { - throw new Error(loadErrorMessage(loaded.error, sessionTargetLabel(target))) + throw new Error(loadErrorMessage(loaded.error, sessionTargetLabel(input))) } return transcriptToTrace(loaded.value) } diff --git a/packages/server/src/sessions/session-target.ts b/packages/server/src/sessions/session-target.ts index 784970c1..452c78f9 100644 --- a/packages/server/src/sessions/session-target.ts +++ b/packages/server/src/sessions/session-target.ts @@ -7,6 +7,8 @@ import type { SessionTarget } from '@rivus/agent-kit/transcript' * A session path as the kit reads it. The kit joins and splits session paths on `/` only (its * Claude Code subagent directory, Codex rollout names, Grok session directories), so on Windows a * path's `\` separators become `/`, which Node's fs also takes. Other systems keep the path as given. + * Every target the server hands the kit goes through this (`loadSession`, `summarizeRow`); the + * kit's own discovery already joins on `/`. */ export function toKitPath(path: string, platform: NodeJS.Platform = process.platform): string { return platform === 'win32' ? path.replaceAll('\\', '/') : path diff --git a/packages/server/src/testsupport/demo-trace.ts b/packages/server/src/testsupport/demo-trace.ts index eba7463f..a60d9ff2 100644 --- a/packages/server/src/testsupport/demo-trace.ts +++ b/packages/server/src/testsupport/demo-trace.ts @@ -1,6 +1,6 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs' import { tmpdir } from 'node:os' -import { join, relative, resolve } from 'node:path' +import { join, relative, resolve, sep } from 'node:path' import process from 'node:process' import { pathToFileURL } from 'node:url' import { createNodePlatform } from '@rivus/agent-kit/node' @@ -24,13 +24,12 @@ export async function writeDemoTrace(out: string): Promise<{ events: number; req const session = writeDemoSession(projectDir, DEMO_CWD) const platform = createNodePlatform({ home, env: {} }) const trace = await loadSession({ agent: 'claude-code', path: session.path }, { platform }) + // `/` in the committed file on every system: `relative` writes Windows separators there. + const inProject = (file: string): string => `tinyshelf/${relative(projectDir, file).split(sep).join('/')}` for (const event of trace.events) { - event.source = { ...event.source, file: `tinyshelf/${relative(projectDir, event.source.file)}` } + event.source = { ...event.source, file: inProject(event.source.file) } } - const skipped = trace.skipped.map(entry => ({ - ...entry, - file: `tinyshelf/${relative(projectDir, entry.file)}`, - })) + const skipped = trace.skipped.map(entry => ({ ...entry, file: inProject(entry.file) })) const text = JSON.stringify({ ...trace, skipped }, null, 1) if (text.includes(home)) { throw new Error('the demo trace still names the temp home') diff --git a/packages/server/test/catalog-cache.test.ts b/packages/server/test/catalog-cache.test.ts index e35644eb..3b48ece0 100644 --- a/packages/server/test/catalog-cache.test.ts +++ b/packages/server/test/catalog-cache.test.ts @@ -6,6 +6,7 @@ import { spawn } from 'node:child_process' import { chmod, mkdir, mkdtemp, readdir, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { dirname, join } from 'node:path' +import process from 'node:process' import { fileURLToPath } from 'node:url' import { CURRENT_TRACE_ID } from '@rivus/estela-rpc' import { openSessionIndex } from '@rivus/estela-runtime-node' @@ -244,10 +245,12 @@ describe('session catalog cache', () => { deferSummaries: true, }) const row = (await redacted.listSessions()).rows[0]! - expect(row.title).toBe('Read ~/notes with [redacted]\nthen stop') + // Redaction keeps the separator after the home directory: `~\notes` on Windows. + const notes = join('~', 'notes') + expect(row.title).toBe(`Read ${notes} with [redacted]\nthen stop`) expect(row.firstPrompt).toBe(row.title) expect(JSON.stringify(await redacted.listSessions())).not.toContain(home) - expect(redacted.pickChoices()[0]?.label).toMatch(/^Read ~\/notes with \[redacted\] then stop · Fake · /) + expect(redacted.pickChoices()[0]?.label.startsWith(`Read ${notes} with [redacted] then stop · Fake · `)).toBe(true) const raw = new SessionCatalog({ platform: createNodePlatform({ home, env: { ESTELA_REDACT: '0' } }), adapters: { fake: adapter }, @@ -272,28 +275,32 @@ describe('session catalog cache', () => { expect(row.lastActiveAt).toBeCloseTo((await stat(bad)).mtimeMs, 3) }) - it('runs without the index when the cache directory is not writable', async () => { - const home = await tempHome() - await session(home, 'a.jsonl', 'Alpha') - const cache = join(home, 'cache') - await mkdir(cache) - await chmod(cache, 0o500) - try { - const catalog = new SessionCatalog({ - platform: createNodePlatform({ home, env: { XDG_CACHE_HOME: cache } }), - adapters: { fake: fakeAdapter(home, []) }, - }) - expect(catalog.indexUnavailable).toMatch(/EACCES|permission/i) - expect(catalog.indexUnavailable).not.toContain(home) - expect(catalog.indexUnavailable).toContain('~/cache') - await catalog.whenIdle() - const listed = await catalog.listSessions({ query: 'Alp' }) - expect(listed.rows[0]?.requests).toBe(1) - expect(listed.matches).toHaveLength(1) - } finally { - await chmod(cache, 0o700) - } - }) + // chmod cannot make a directory read-only on Windows. + it.skipIf(process.platform === 'win32')( + 'runs without the index when the cache directory is not writable', + async () => { + const home = await tempHome() + await session(home, 'a.jsonl', 'Alpha') + const cache = join(home, 'cache') + await mkdir(cache) + await chmod(cache, 0o500) + try { + const catalog = new SessionCatalog({ + platform: createNodePlatform({ home, env: { XDG_CACHE_HOME: cache } }), + adapters: { fake: fakeAdapter(home, []) }, + }) + expect(catalog.indexUnavailable).toMatch(/EACCES|permission/i) + expect(catalog.indexUnavailable).not.toContain(home) + expect(catalog.indexUnavailable).toContain('~/cache') + await catalog.whenIdle() + const listed = await catalog.listSessions({ query: 'Alp' }) + expect(listed.rows[0]?.requests).toBe(1) + expect(listed.matches).toHaveLength(1) + } finally { + await chmod(cache, 0o700) + } + }, + ) it('gives a file opened by path the same trace id as its list row', async () => { const home = await tempHome() From 2b2a6f3e33ae52634666c747c8ff159ef942362b Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:15:10 +0800 Subject: [PATCH 6/9] fix(cli): skip a default export name taken by a dangling link on Windows 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 --- .changeset/windows-paths-and-index-rebuild.md | 3 +- apps/cli/src/entry/app.test.ts | 31 +++++++++++-------- apps/cli/src/export/write-export.ts | 18 +++++++++++ apps/e2e/src/cli-process.ts | 17 ++++++---- apps/e2e/src/cli.smoke.ts | 2 +- apps/e2e/src/e2e/harness.ts | 2 +- apps/e2e/src/e2e/security.e2e.ts | 4 ++- apps/e2e/src/mcp.smoke.ts | 6 ++-- .../runtime-node/src/session-index-schema.ts | 8 +++-- .../runtime-node/src/session-index.test.ts | 12 +++++++ .../server/src/sessions/load-session.test.ts | 11 ++++--- .../server/src/sessions/session-target.ts | 6 ++-- packages/server/test/catalog-cache.test.ts | 8 +++-- packages/server/test/session-view.test.ts | 4 ++- 14 files changed, 94 insertions(+), 38 deletions(-) diff --git a/.changeset/windows-paths-and-index-rebuild.md b/.changeset/windows-paths-and-index-rebuild.md index 96aba3ef..0e78faef 100644 --- a/.changeset/windows-paths-and-index-rebuild.md +++ b/.changeset/windows-paths-and-index-rebuild.md @@ -4,5 +4,6 @@ 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, a Codex rollout and a Grok session given by path are recognized, and a session opened by path gets the same trace id as when it is picked from the session list. +- 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/` 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. diff --git a/apps/cli/src/entry/app.test.ts b/apps/cli/src/entry/app.test.ts index bf9d102f..9e566c50 100644 --- a/apps/cli/src/entry/app.test.ts +++ b/apps/cli/src/entry/app.test.ts @@ -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' } @@ -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() @@ -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() @@ -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 }) } diff --git a/apps/cli/src/export/write-export.ts b/apps/cli/src/export/write-export.ts index dddde6d3..f9b8cbf0 100644 --- a/apps/cli/src/export/write-export.ts +++ b/apps/cli/src/export/write-export.ts @@ -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 { + try { + await lstat(path) + return true + } catch (error) { + if (errorCode(error) === 'ENOENT') { + return false + } + throw error + } +} + async function writeDefaultUnique( sessionId: string, format: ExportFormat, @@ -55,6 +68,11 @@ 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. + if (await entryExists(candidate)) { + continue + } try { const handle = await open(candidate, 'wx') try { diff --git a/apps/e2e/src/cli-process.ts b/apps/e2e/src/cli-process.ts index 39664ee6..0ae3c3af 100644 --- a/apps/e2e/src/cli-process.ts +++ b/apps/e2e/src/cli-process.ts @@ -3,7 +3,7 @@ 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 { delimiter, 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' @@ -14,18 +14,23 @@ 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` (and `USERPROFILE`, which `os.homedir()` reads on - * Windows), 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`). + * 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 = {}): NodeJS.ProcessEnv { const env: NodeJS.ProcessEnv = { ...process.env } @@ -51,7 +56,7 @@ export function smokeEnv(where: CliHome, openLog: string, extra: Record { holders.push(holder) } } - const server = start(ctx.node, [ctx.bin, ctx.claudePlain], { + const server = start(ctx.node, [ctx.bin, ctx.claudePlain, '--no-open'], { cwd: ctx.installDir, env: smokeEnv(ctx, openLogPath(ctx, 'port-fallback')), }) diff --git a/apps/e2e/src/e2e/harness.ts b/apps/e2e/src/e2e/harness.ts index ac08bec3..699c8321 100644 --- a/apps/e2e/src/e2e/harness.ts +++ b/apps/e2e/src/e2e/harness.ts @@ -108,7 +108,7 @@ export const test = base.extend({ const home = options.home ?? ctx.homes.main.home const server = start(process.execPath, [ctx.bin, ...(options.args ?? []), '--port', '0'], { cwd, - env: smokeEnv({ home, cache, fakeBin: ctx.fakeBin }, openLog, options.env), + env: smokeEnv({ home, cache, fakeBin: ctx.fakeBin, node: ctx.node }, openLog, options.env), }) servers.push(server) const ready = () => READY.exec(server.output().stdout) diff --git a/apps/e2e/src/e2e/security.e2e.ts b/apps/e2e/src/e2e/security.e2e.ts index 1599198e..4089dd3d 100644 --- a/apps/e2e/src/e2e/security.e2e.ts +++ b/apps/e2e/src/e2e/security.e2e.ts @@ -86,7 +86,9 @@ test('build report neutralizes hostile session payloads, enforces strict SHA-256 try { await writeFile(sessionPath, `${lines.join('\n')}\n`, 'utf8') - const env = smokeEnv({ home, cache, fakeBin: ctx.fakeBin }, join(dir, 'open.log'), { ESTELA_REDACT: '0' }) + const env = smokeEnv({ home, cache, fakeBin: ctx.fakeBin, node: ctx.node }, join(dir, 'open.log'), { + ESTELA_REDACT: '0', + }) await exec(process.execPath, [ctx.bin, 'build', sessionPath, '--out-dir', outDir], { cwd: dir, env }) const html = await readFile(join(outDir, 'index.html'), 'utf8') diff --git a/apps/e2e/src/mcp.smoke.ts b/apps/e2e/src/mcp.smoke.ts index f2dc8783..32c32322 100644 --- a/apps/e2e/src/mcp.smoke.ts +++ b/apps/e2e/src/mcp.smoke.ts @@ -103,7 +103,9 @@ describe('mcp without a path: the session catalog', () => { await mkdir(cache, { recursive: true }) server = start(ctx.node, [ctx.bin, 'mcp'], { cwd: ctx.installDir, - env: smokeEnv({ home, cache, fakeBin: ctx.fakeBin }, openLogPath(ctx, 's17'), { ESTELA_REDACT: '0' }), + env: smokeEnv({ home, cache, fakeBin: ctx.fakeBin, node: ctx.node }, openLogPath(ctx, 's17'), { + ESTELA_REDACT: '0', + }), input: true, }) client = mcpClient(server) @@ -194,7 +196,7 @@ describe('mcp over HTTP from the dev server', () => { // The wildcard bind takes connections from the LAN; the route must still refuse them. const server = start(ctx.node, [ctx.bin, '--mcp', '--no-open', '--host', '0.0.0.0', '--port', '0'], { cwd: ctx.installDir, - env: smokeEnv({ home, cache, fakeBin: ctx.fakeBin }, openLogPath(ctx, 'mcp-http')), + env: smokeEnv({ home, cache, fakeBin: ctx.fakeBin, node: ctx.node }, openLogPath(ctx, 'mcp-http')), }) try { const ready = /Ready: http:\/\/127\.0\.0\.1:(\d+)\/__estela\// diff --git a/packages/runtime-node/src/session-index-schema.ts b/packages/runtime-node/src/session-index-schema.ts index 701e9f45..94d176a5 100644 --- a/packages/runtime-node/src/session-index-schema.ts +++ b/packages/runtime-node/src/session-index-schema.ts @@ -87,9 +87,11 @@ export function isTransient(error: unknown): boolean { /** * Windows refuses to delete a file that another process has open (SQLite opens it without - * `FILE_SHARE_DELETE`), so a rebuild's delete fails with EPERM or EBUSY while another opener still - * holds the broken file; that opener lets go before its next try. On POSIX these codes are real - * permission problems. + * `FILE_SHARE_DELETE`), so a rebuild's delete fails with EPERM or EBUSY while another process holds + * the broken file. A process in this open loop lets go before its next try; one that keeps the file + * open (an older Estela still running) holds it past `LOCK_WAIT_MS`, and the opener then runs + * without the index, as it would after a real permission error. Node reports a file in use as + * EPERM too, so EPERM cannot be left out. On POSIX these codes are real permission problems. */ function isOpenElsewhere(error: unknown): boolean { return process.platform === 'win32' && z.safeParse(fileInUse, error).success diff --git a/packages/runtime-node/src/session-index.test.ts b/packages/runtime-node/src/session-index.test.ts index c176ccb9..8210c448 100644 --- a/packages/runtime-node/src/session-index.test.ts +++ b/packages/runtime-node/src/session-index.test.ts @@ -326,6 +326,18 @@ describe('session index', () => { }, ) + // The disabled path on every system, Windows included: a file where the cache directory should be. + it('returns a disabled index with the reason when the cache directory cannot be created', async () => { + const blocker = join(await tempDir(), 'not-a-directory') + writeFileSync(blocker, '') + const index = openSessionIndex({ summaryVersion: 1, env: { XDG_CACHE_HOME: blocker }, homeDir: '/h/u' }) + expect(index.enabled).toBe(false) + // The error code differs by system (ENOTDIR on macOS and Linux); a reason is what counts. + expect(index.unavailable).toMatch(/ENOTDIR|EEXIST|ENOENT|not a directory/i) + expect(index.search('x')).toBeUndefined() + index.close() + }) + it('lets several processes open a fresh cache at once', async () => { const dir = await tempDir() const file = join(dir, 'index.sqlite') diff --git a/packages/server/src/sessions/load-session.test.ts b/packages/server/src/sessions/load-session.test.ts index 6989abe7..c53e1edb 100644 --- a/packages/server/src/sessions/load-session.test.ts +++ b/packages/server/src/sessions/load-session.test.ts @@ -6,6 +6,7 @@ import { createNodePlatform } from '@rivus/agent-kit/node' import type { SessionAdapter } from '@rivus/agent-kit/sessions' import { afterEach, describe, expect, it } from 'vite-plus/test' import { loadSession } from './load-session.ts' +import { toKitPath } from './session-target.ts' import { MAX_CANONICAL_TRACE_BYTES } from './node-platform.ts' import { builtinAdapters } from './adapters.ts' import { createTraceStore } from '../store/trace-store.ts' @@ -128,7 +129,7 @@ describe('loadSession', () => { it('throws the unknown-generation wording, which the web parses into agent, file, and line', async () => { const path = await unknownGeneration() await expect(loadSession({ path }, { platform: createNodePlatform({ home: '/u/me', env: {} }) })).rejects.toThrow( - `claude-code: ${path}:1: unknown format generation`, + `claude-code: ${toKitPath(path)}:1: unknown format generation`, ) }) @@ -176,7 +177,7 @@ describe('loadSession', () => { })}\n`, ) await expect(loadSession({ path }, { platform: createNodePlatform({ home: '/u/me', env: {} }) })).rejects.toThrow( - `claude-code: ${path}:1: unknown format generation`, + `claude-code: ${toKitPath(path)}:1: unknown format generation`, ) }) @@ -242,19 +243,21 @@ describe('loadSession', () => { const path = join(dir, 'huge.trace.json') await writeFile(path, canonicalHook({ type: 'hook_success', name: 'PreToolUse' })) const base = createNodePlatform({ home: dir, env: {} }) + // `loadSession` reads the `toKitPath` form of the path. + const read = toKitPath(path) const wrapped = { ...base, fs: { ...base.fs, async stat(file: string, options?: { readonly followSymlinks?: boolean }) { const actual = await base.fs.stat(file, options) - if (file === path && actual) { + if (file === read && actual) { return { ...actual, size: MAX_CANONICAL_TRACE_BYTES + 1 } } return actual }, read(file: string, range?: { readonly start: number; readonly end?: number }) { - if (file === path && range?.end === undefined) { + if (file === read && range?.end === undefined) { throw new Error('should not read the full oversized file') } return base.fs.read(file, range) diff --git a/packages/server/src/sessions/session-target.ts b/packages/server/src/sessions/session-target.ts index 452c78f9..d4d56098 100644 --- a/packages/server/src/sessions/session-target.ts +++ b/packages/server/src/sessions/session-target.ts @@ -18,8 +18,10 @@ export function toKitPath(path: string, platform: NodeJS.Platform = process.plat * The trace id of a session: an opaque hash of agent and path, plus the session id when the path * addresses one session inside a file that holds several (the `path#id` form). The catalog turns it * back into a target. URLs and the session index hold these ids, so the hashed input must stay exactly this. - * The path is hashed in its {@link toKitPath} form: on Windows discovery yields the home directory's - * `\` followed by the kit's `/`, and a path typed on the command line has `\` only. + * The path is hashed in its {@link toKitPath} form, which leaves POSIX paths as they are. On Windows + * discovery yields the home directory's `\` followed by the kit's `/`, and a path typed on the + * command line has `\` only; both hash as `/`. Letter case still counts: `c:\users` and `C:\Users` + * get two ids. */ export function traceIdOf(target: { agent: string; path: string; sessionId?: string }): string { return createHash('sha256') diff --git a/packages/server/test/catalog-cache.test.ts b/packages/server/test/catalog-cache.test.ts index 3b48ece0..3942602d 100644 --- a/packages/server/test/catalog-cache.test.ts +++ b/packages/server/test/catalog-cache.test.ts @@ -13,7 +13,7 @@ import { openSessionIndex } from '@rivus/estela-runtime-node' import { afterEach, describe, expect, it } from 'vite-plus/test' import { SessionCatalog } from '../src/catalog/session-catalog.ts' import { loadSession } from '../src/sessions/load-session.ts' -import { oneLine } from '../src/sessions/session-target.ts' +import { oneLine, toKitPath } from '../src/sessions/session-target.ts' import { createTraceStore } from '../src/store/trace-store.ts' const repo = join(dirname(fileURLToPath(import.meta.url)), '../../..') @@ -193,7 +193,8 @@ describe('session catalog cache', () => { expect(listed.rows[0]?.pending).toBe(true) await current.whenIdle() expect((await current.listSessions()).rows[0]?.requests).toBe(1) - expect(loads).toEqual([path, path]) + // `summarizeRow` hands the kit the `toKitPath` form of the discovered path. + expect(loads).toEqual([toKitPath(path), toKitPath(path)]) current.close() }) @@ -223,7 +224,8 @@ describe('session catalog cache', () => { await current.whenIdle() const done = await current.listSessions() expect(done.rows[0]?.requests).toBe(1) - expect(loads).toEqual([path, path]) + // `summarizeRow` hands the kit the `toKitPath` form of the discovered path. + expect(loads).toEqual([toKitPath(path), toKitPath(path)]) // The recomputed prompts are searchable through the index. const found = await current.listSessions({ query: 'hello' }) expect(found.matches).toEqual([done.rows[0]?.traceId]) diff --git a/packages/server/test/session-view.test.ts b/packages/server/test/session-view.test.ts index d0a3561f..ed845d30 100644 --- a/packages/server/test/session-view.test.ts +++ b/packages/server/test/session-view.test.ts @@ -6,12 +6,14 @@ import { fold, projectLanes, reconstruct, summaryOf, toView } from '@rivus/estel import { describe, expect, it } from 'vite-plus/test' import { summarizeRow } from '../src/catalog/rows.ts' import { loadSession } from '../src/sessions/load-session.ts' +import { toKitPath } from '../src/sessions/session-target.ts' import { transcriptToTrace } from '../src/sessions/transcript-trace.ts' const here = dirname(fileURLToPath(import.meta.url)) const repo = join(here, '../../..') +/** In the form the server hands the kit (`toKitPath`): `loadTranscript` below is the kit's own call. */ const fixture = (agent: string, relative: string): string => - join(repo, 'fixtures/sessions', agent, 'conformance', relative) + toKitPath(join(repo, 'fixtures/sessions', agent, 'conformance', relative)) const platform = createNodePlatform() const claudeLoad = async (relative: string) => From 1b6f15db1f74430bdef7328f1266f33032d43d1c Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:18:51 +0800 Subject: [PATCH 7/9] docs: name macOS, Linux, and Windows as supported systems Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- README.zh-CN.md | 2 +- docs/guide/getting-started.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 24b9dfed..70f6776a 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/README.zh-CN.md b/README.zh-CN.md index bd0cabb5..41921808 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -28,7 +28,7 @@ npx @rivus/estela ``` -需要 Node.js 24 或更高版本。它列出本机 Agent 的会话,并在浏览器中打开。任何数据都不会离开本机。 +需要 Node.js 24 或更高版本,支持 macOS、Linux 和 Windows。它列出本机 Agent 的会话,并在浏览器中打开。任何数据都不会离开本机。 ## 用途 diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index 6c17ebaa..f8f35867 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -2,7 +2,7 @@ ## Run it -Estela needs Node.js 24 or later. Run it without installing: +Estela needs Node.js 24 or later and runs on macOS, Linux, and Windows. Run it without installing: ```sh npx @rivus/estela From 2d788c2ec4d3a35a14eb00dd8b1e66e0dba5b51f Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:27:38 +0800 Subject: [PATCH 8/9] test: cover the server's Windows path handling and run the no-index catalog 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 --- apps/cli/src/export/write-export.ts | 4 +- apps/e2e/src/e2e/harness.ts | 2 +- packages/server/test/catalog-cache.test.ts | 47 +++++++++------------- packages/server/test/session-view.test.ts | 7 ++-- 4 files changed, 28 insertions(+), 32 deletions(-) diff --git a/apps/cli/src/export/write-export.ts b/apps/cli/src/export/write-export.ts index f9b8cbf0..b10c3d58 100644 --- a/apps/cli/src/export/write-export.ts +++ b/apps/cli/src/export/write-export.ts @@ -69,7 +69,9 @@ async function writeDefaultUnique( 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. + // 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 } diff --git a/apps/e2e/src/e2e/harness.ts b/apps/e2e/src/e2e/harness.ts index 699c8321..39d2c5f2 100644 --- a/apps/e2e/src/e2e/harness.ts +++ b/apps/e2e/src/e2e/harness.ts @@ -106,7 +106,7 @@ export const test = base.extend({ await mkdir(cache, { recursive: true }) const openLog = join(cwd, 'opened.log') const home = options.home ?? ctx.homes.main.home - const server = start(process.execPath, [ctx.bin, ...(options.args ?? []), '--port', '0'], { + const server = start(ctx.node, [ctx.bin, ...(options.args ?? []), '--port', '0'], { cwd, env: smokeEnv({ home, cache, fakeBin: ctx.fakeBin, node: ctx.node }, openLog, options.env), }) diff --git a/packages/server/test/catalog-cache.test.ts b/packages/server/test/catalog-cache.test.ts index 3942602d..53494258 100644 --- a/packages/server/test/catalog-cache.test.ts +++ b/packages/server/test/catalog-cache.test.ts @@ -3,7 +3,7 @@ import type { Transcript } from '@rivus/agent-kit/transcript' import { ok } from '@rivus/agent-kit/catalog' import { createNodePlatform } from '@rivus/agent-kit/node' import { spawn } from 'node:child_process' -import { chmod, mkdir, mkdtemp, readdir, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises' +import { mkdir, mkdtemp, readdir, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises' import { tmpdir } from 'node:os' import { dirname, join } from 'node:path' import process from 'node:process' @@ -277,32 +277,25 @@ describe('session catalog cache', () => { expect(row.lastActiveAt).toBeCloseTo((await stat(bad)).mtimeMs, 3) }) - // chmod cannot make a directory read-only on Windows. - it.skipIf(process.platform === 'win32')( - 'runs without the index when the cache directory is not writable', - async () => { - const home = await tempHome() - await session(home, 'a.jsonl', 'Alpha') - const cache = join(home, 'cache') - await mkdir(cache) - await chmod(cache, 0o500) - try { - const catalog = new SessionCatalog({ - platform: createNodePlatform({ home, env: { XDG_CACHE_HOME: cache } }), - adapters: { fake: fakeAdapter(home, []) }, - }) - expect(catalog.indexUnavailable).toMatch(/EACCES|permission/i) - expect(catalog.indexUnavailable).not.toContain(home) - expect(catalog.indexUnavailable).toContain('~/cache') - await catalog.whenIdle() - const listed = await catalog.listSessions({ query: 'Alp' }) - expect(listed.rows[0]?.requests).toBe(1) - expect(listed.matches).toHaveLength(1) - } finally { - await chmod(cache, 0o700) - } - }, - ) + // A file where the cache directory should be fails the index on every system; chmod cannot make + // a directory read-only on Windows. + it('runs without the index when the cache directory cannot be created', async () => { + const home = await tempHome() + await session(home, 'a.jsonl', 'Alpha') + const cache = join(home, 'cache') + await writeFile(cache, '') + const catalog = new SessionCatalog({ + platform: createNodePlatform({ home, env: { XDG_CACHE_HOME: cache } }), + adapters: { fake: fakeAdapter(home, []) }, + }) + expect(catalog.indexUnavailable).toMatch(/ENOTDIR|EEXIST|ENOENT|not a directory/i) + expect(catalog.indexUnavailable).not.toContain(home) + expect(catalog.indexUnavailable).toContain(join('~', 'cache')) + await catalog.whenIdle() + const listed = await catalog.listSessions({ query: 'Alp' }) + expect(listed.rows[0]?.requests).toBe(1) + expect(listed.matches).toHaveLength(1) + }) it('gives a file opened by path the same trace id as its list row', async () => { const home = await tempHome() diff --git a/packages/server/test/session-view.test.ts b/packages/server/test/session-view.test.ts index ed845d30..d64e755d 100644 --- a/packages/server/test/session-view.test.ts +++ b/packages/server/test/session-view.test.ts @@ -11,9 +11,9 @@ import { transcriptToTrace } from '../src/sessions/transcript-trace.ts' const here = dirname(fileURLToPath(import.meta.url)) const repo = join(here, '../../..') -/** In the form the server hands the kit (`toKitPath`): `loadTranscript` below is the kit's own call. */ +/** This system's spelling (`\\` on Windows), so `loadSession` and `summarizeRow` turn it into the kit's form. */ const fixture = (agent: string, relative: string): string => - toKitPath(join(repo, 'fixtures/sessions', agent, 'conformance', relative)) + join(repo, 'fixtures/sessions', agent, 'conformance', relative) const platform = createNodePlatform() const claudeLoad = async (relative: string) => @@ -52,7 +52,8 @@ describe('catalog summary equals the workspace header summary', () => { for (const [agent, relative] of FIXTURES) { it(`${agent} ${relative}`, async () => { const path = fixture(agent, relative) - const loaded = await loadTranscript(platform, { agent, path }) + // The kit's own call: it gets the path in the form the server hands it. + const loaded = await loadTranscript(platform, { agent, path: toKitPath(path) }) if (!loaded.ok) { throw new Error(`${path}: ${loaded.error._tag}`) } From 3074c60f59f5bcceeebb84bd57bfbb5e5d1ee751 Mon Sep 17 00:00:00 2001 From: PerfectPan <24316656+PerfectPan@users.noreply.github.com> Date: Tue, 17 Nov 2026 16:32:18 +0800 Subject: [PATCH 9/9] test: wait for the catalog test's lock holder to exit before cleanup Co-Authored-By: Claude Opus 5.5 --- packages/server/test/catalog-cache.test.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/server/test/catalog-cache.test.ts b/packages/server/test/catalog-cache.test.ts index 53494258..ace3867a 100644 --- a/packages/server/test/catalog-cache.test.ts +++ b/packages/server/test/catalog-cache.test.ts @@ -391,6 +391,7 @@ describe('session catalog cache', () => { ], { stdio: ['ignore', 'pipe', 'inherit'] }, ) + const holderExited = new Promise(resolve => holder.once('exit', () => resolve())) await new Promise(resolve => holder.stdout.once('data', () => resolve())) try { const started = performance.now() @@ -412,6 +413,8 @@ describe('session catalog cache', () => { second.close() } finally { holder.kill() + // Windows keeps the holder's index files locked until it has exited, and the temp home goes after the test. + await holderExited } })