devharness 0.9.7 → 0.9.9

package/build/session-endpoint.js

@@ -0,0 +1,220 @@
+/**
+ * Session endpoint - the private channel a CLI process uses to run a tool
+ * inside this MCP session, against the connections this session already holds.
+ *
+ * A unix socket, not a TCP port. The tools reachable here evaluate JavaScript
+ * in the session's browser and read its cookies; a web page can reach a
+ * localhost port and cannot open a socket file, so the address type is the
+ * access control.
+ *
+ * On Windows the address is a named pipe. Node's `net` API is identical for
+ * both, and libuv rejects remote clients, but a pipe carries no mode bits -
+ * the 0600 guarantee holds on POSIX only.
+ */
+import { createServer } from 'net';
+import { promises as fs, existsSync, readFileSync, readdirSync, unlinkSync, chmodSync } from 'fs';
+import { join } from 'path';
+import { getOutputPath, getTempPath } from './helpers/paths.js';
+import { isProcessAlive } from './helpers/process-liveness.js';
+/** sun_path is 104 bytes on macOS and 108 on Linux; a path near that length
+ *  fails to bind with ENAMETOOLONG. */
+const MAX_SOCKET_PATH = 96;
+/** Owned by this feature alone: `~/.devharness/sessions/` already holds the
+ *  supervisor presence records `server-claims.ts` writes, under a different
+ *  schema. */
+export function getEndpointsDir() {
+    return getOutputPath('endpoints', { global: true });
+}
+export function getPresencePath(pid) {
+    return join(getEndpointsDir(), `${pid}.json`);
+}
+/** The listen address for `pid`: a named pipe on Windows, a socket file under
+ *  the sessions directory otherwise, falling back to the temp directory when
+ *  that path would exceed the sockaddr limit. */
+export function getEndpointAddress(pid) {
+    if (process.platform === 'win32') {
+        return `\\\\.\\pipe\\devharness-${pid}`;
+    }
+    const preferred = join(getEndpointsDir(), `${pid}.sock`);
+    if (preferred.length <= MAX_SOCKET_PATH)
+        return preferred;
+    return getTempPath(`session-${pid}.sock`);
+}
+/** Every session record on disk, newest first. Records naming a dead process
+ *  are dropped and their files removed: a killed session leaves both behind,
+ *  and a CLI matching against one would dial a socket nothing is listening on. */
+export function listSessionRecords() {
+    let entries;
+    try {
+        entries = readdirSync(getEndpointsDir());
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.json'))
+            continue;
+        const path = join(getEndpointsDir(), entry);
+        let record;
+        try {
+            record = JSON.parse(readFileSync(path, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        if (!record?.pid || !record.address)
+            continue;
+        if (!isProcessAlive(record.pid)) {
+            try {
+                unlinkSync(path);
+            }
+            catch { /* another process swept it first */ }
+            if (process.platform !== 'win32') {
+                try {
+                    unlinkSync(record.address);
+                }
+                catch { /* already gone */ }
+            }
+            continue;
+        }
+        records.push(record);
+    }
+    // A rebuild restarts every child at once, so startedAt ties are the norm
+    // rather than the exception; without the pid the order is readdir's, and
+    // `--session=<shortId>` would resolve to a different server run to run.
+    return records.sort((a, b) => b.startedAt - a.startedAt || a.pid - b.pid);
+}
+/**
+ * Listen for CLI tool calls and publish the presence record that locates this
+ * session. Returns null when the listener cannot bind - the MCP session keeps
+ * working, the CLI just cannot reach it.
+ */
+export async function startSessionEndpoint(options) {
+    const pid = options.identity.pid;
+    const address = getEndpointAddress(pid);
+    const presencePath = getPresencePath(pid);
+    await fs.mkdir(getEndpointsDir(), { recursive: true });
+    // A previous process with this pid, or this process before a crash, leaves a
+    // socket file that bind() refuses. Nothing is listening on it - the pid check
+    // in listSessionRecords already proved that for every record we keep.
+    if (process.platform !== 'win32' && existsSync(address)) {
+        try {
+            unlinkSync(address);
+        }
+        catch { /* bind will report it */ }
+    }
+    const server = createServer((socket) => {
+        handleConnection(socket, options);
+    });
+    const bound = await new Promise((resolve) => {
+        server.once('error', (error) => {
+            console.error(`[devharness] session endpoint failed to listen on ${address}: ${error.message}`);
+            resolve(false);
+        });
+        server.listen(address, () => resolve(true));
+    });
+    if (!bound)
+        return null;
+    // Owner-only. On Windows the pipe carries no mode bits, so this is skipped
+    // and another account on the machine may be able to connect.
+    if (process.platform !== 'win32') {
+        try {
+            chmodSync(address, 0o600);
+        }
+        catch { /* best effort */ }
+    }
+    const record = {
+        ...options.identity,
+        address,
+        startedAt: Date.now(),
+    };
+    await writeRecord(presencePath, record);
+    return {
+        address,
+        presencePath,
+        async refresh(identity) {
+            Object.assign(record, identity);
+            await writeRecord(presencePath, record);
+        },
+        async close() {
+            await new Promise((resolve) => server.close(() => resolve()));
+            try {
+                unlinkSync(presencePath);
+            }
+            catch { /* already gone */ }
+            if (process.platform !== 'win32') {
+                try {
+                    unlinkSync(address);
+                }
+                catch { /* already gone */ }
+            }
+        },
+    };
+}
+async function writeRecord(path, record) {
+    const temp = `${path}.${process.pid}.tmp`;
+    await fs.writeFile(temp, JSON.stringify(record), { mode: 0o600 });
+    await fs.rename(temp, path);
+}
+/**
+ * One request per connection: a single JSON line in, a single JSON line out,
+ * then close. A tool response carries no framing of its own, so the newline is
+ * what tells the caller the reply is complete.
+ */
+function handleConnection(socket, options) {
+    let buffer = '';
+    let handled = false;
+    // A caller that gives up - its own timeout, or a Ctrl-C - takes the work with
+    // it. Without this a `message send` holding for a reply keeps waiting after
+    // the CLI has gone, receives the reply, marks it read and answers nobody.
+    const controller = new AbortController();
+    const abandon = () => controller.abort();
+    socket.setEncoding('utf-8');
+    socket.on('error', abandon);
+    socket.on('close', abandon);
+    socket.on('data', (chunk) => {
+        if (handled)
+            return;
+        buffer += chunk;
+        const newline = buffer.indexOf('\n');
+        if (newline === -1)
+            return;
+        handled = true;
+        const line = buffer.slice(0, newline);
+        void respond(socket, line, options, controller.signal);
+    });
+}
+async function respond(socket, line, options, abortSignal) {
+    const send = (reply) => {
+        socket.end(JSON.stringify(reply) + '\n');
+    };
+    let request;
+    try {
+        request = JSON.parse(line);
+    }
+    catch {
+        send({ ok: false, error: 'Request was not a single line of JSON' });
+        return;
+    }
+    if (!request?.tool || typeof request.tool !== 'string') {
+        send({ ok: false, error: 'Request needs a tool name' });
+        return;
+    }
+    try {
+        if (options.awaitReady)
+            await options.awaitReady();
+        const response = await options.executeToolCall(request.tool, request.args ?? {}, abortSignal);
+        send({ ok: true, response });
+    }
+    catch (error) {
+        // executeToolCall throws ToolError for an isError response; its payload is
+        // the response itself, which the caller renders like any other.
+        if (error?.response) {
+            send({ ok: true, response: error.response });
+            return;
+        }
+        send({ ok: false, error: error?.message || String(error) });
+    }
+}
+//# sourceMappingURL=session-endpoint.js.map

package/build/session-endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-endpoint.js","sourceRoot":"","sources":["../src/session-endpoint.ts"],"names":[],"mappings":"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"}

package/build/session-endpoint.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tests for the socket a CLI process calls tools through.
+ *
+ * The round-trip cases bind a real socket in a temp DEVHARNESS_DIR and connect
+ * to it, because the things worth asserting - that a ToolError comes back as a
+ * renderable response, that a half-written request does not reply early - are
+ * properties of the framing, not of a mocked handler.
+ */
+export {};
+//# sourceMappingURL=session-endpoint.test.d.ts.map

package/build/session-endpoint.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-endpoint.test.d.ts","sourceRoot":"","sources":["../src/session-endpoint.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/build/session-endpoint.test.js

@@ -0,0 +1,202 @@
+/**
+ * Tests for the socket a CLI process calls tools through.
+ *
+ * The round-trip cases bind a real socket in a temp DEVHARNESS_DIR and connect
+ * to it, because the things worth asserting - that a ToolError comes back as a
+ * renderable response, that a half-written request does not reply early - are
+ * properties of the framing, not of a mocked handler.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { connect } from 'net';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, statSync, mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { initializePaths } from './helpers/paths.js';
+import { startSessionEndpoint, listSessionRecords, getEndpointsDir, getEndpointAddress, getPresencePath, } from './session-endpoint.js';
+const posixOnly = process.platform === 'win32' ? it.skip : it;
+let dir;
+let previousDir;
+let endpoint = null;
+beforeEach(() => {
+    previousDir = process.env.DEVHARNESS_DIR;
+    dir = mkdtempSync(join(tmpdir(), 'devharness-endpoint-'));
+    process.env.DEVHARNESS_DIR = dir;
+    initializePaths();
+});
+afterEach(async () => {
+    if (endpoint) {
+        await endpoint.close();
+        endpoint = null;
+    }
+    if (previousDir === undefined)
+        delete process.env.DEVHARNESS_DIR;
+    else
+        process.env.DEVHARNESS_DIR = previousDir;
+    initializePaths();
+    rmSync(dir, { recursive: true, force: true });
+});
+/** One request over the socket, resolving with the parsed reply. */
+function callEndpoint(address, payload) {
+    return new Promise((resolve, reject) => {
+        let buffer = '';
+        const socket = connect(address);
+        socket.setEncoding('utf-8');
+        socket.on('connect', () => socket.write(JSON.stringify(payload) + '\n'));
+        socket.on('data', (chunk) => {
+            buffer += chunk;
+            const newline = buffer.indexOf('\n');
+            if (newline === -1)
+                return;
+            socket.destroy();
+            try {
+                resolve(JSON.parse(buffer.slice(0, newline)));
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        socket.on('error', reject);
+    });
+}
+const IDENTITY = { pid: process.pid, ppid: process.ppid, cwd: '/repo' };
+// ---------------------------------------------------------------------------
+// addresses
+// ---------------------------------------------------------------------------
+describe('getEndpointAddress', () => {
+    posixOnly('puts the socket beside the presence record', () => {
+        expect(getEndpointAddress(1234)).toBe(join(getEndpointsDir(), '1234.sock'));
+        expect(getPresencePath(1234)).toBe(join(getEndpointsDir(), '1234.json'));
+    });
+    posixOnly('falls back to the temp directory when the path would exceed the sockaddr limit', () => {
+        process.env.DEVHARNESS_DIR = join(dir, 'x'.repeat(120));
+        initializePaths();
+        const address = getEndpointAddress(1234);
+        expect(address).not.toContain('x'.repeat(120));
+        expect(address).toContain('session-1234.sock');
+    });
+});
+// ---------------------------------------------------------------------------
+// round trip
+// ---------------------------------------------------------------------------
+describe('endpoint round trip', () => {
+    posixOnly('runs the named tool and returns its response', async () => {
+        const calls = [];
+        endpoint = await startSessionEndpoint({
+            executeToolCall: async (tool, args) => {
+                calls.push({ tool, args });
+                return { content: [{ type: 'text', text: 'ran it' }], _meta: { tool } };
+            },
+            identity: IDENTITY,
+        });
+        const reply = await callEndpoint(endpoint.address, { tool: 'config', args: { action: 'status' } });
+        expect(reply.ok).toBe(true);
+        expect(reply.response.content[0].text).toBe('ran it');
+        expect(calls).toEqual([{ tool: 'config', args: { action: 'status' } }]);
+    });
+    posixOnly('returns a ToolError\'s response, so an error renders like any other result', async () => {
+        const failure = { content: [{ type: 'text', text: 'nope' }], isError: true, _errorId: 'SOME_ERROR' };
+        endpoint = await startSessionEndpoint({
+            executeToolCall: async () => { throw Object.assign(new Error('nope'), { response: failure }); },
+            identity: IDENTITY,
+        });
+        const reply = await callEndpoint(endpoint.address, { tool: 'whatever', args: {} });
+        expect(reply.ok).toBe(true);
+        expect(reply.response).toEqual(failure);
+    });
+    posixOnly('reports a throw that carries no response as a failed call', async () => {
+        endpoint = await startSessionEndpoint({
+            executeToolCall: async () => { throw new Error('Unknown tool: nope'); },
+            identity: IDENTITY,
+        });
+        const reply = await callEndpoint(endpoint.address, { tool: 'nope', args: {} });
+        expect(reply.ok).toBe(false);
+        expect(reply.error).toBe('Unknown tool: nope');
+    });
+    posixOnly('rejects a request that is not JSON', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({}), identity: IDENTITY });
+        const reply = await new Promise((resolve, reject) => {
+            let buffer = '';
+            const socket = connect(endpoint.address);
+            socket.setEncoding('utf-8');
+            socket.on('connect', () => socket.write('not json\n'));
+            socket.on('data', (chunk) => {
+                buffer += chunk;
+                if (!buffer.includes('\n'))
+                    return;
+                socket.destroy();
+                resolve(JSON.parse(buffer.split('\n')[0]));
+            });
+            socket.on('error', reject);
+        });
+        expect(reply.ok).toBe(false);
+        expect(reply.error).toMatch(/single line of JSON/);
+    });
+    posixOnly('rejects a request with no tool name', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({}), identity: IDENTITY });
+        const reply = await callEndpoint(endpoint.address, { args: {} });
+        expect(reply.ok).toBe(false);
+        expect(reply.error).toMatch(/tool name/);
+    });
+    posixOnly('binds over a socket file left by a process that was killed', async () => {
+        mkdirSync(getEndpointsDir(), { recursive: true });
+        writeFileSync(getEndpointAddress(process.pid), '');
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({ content: [] }), identity: IDENTITY });
+        expect(endpoint).not.toBeNull();
+        const reply = await callEndpoint(endpoint.address, { tool: 'x', args: {} });
+        expect(reply.ok).toBe(true);
+    });
+    posixOnly('gives the socket and the record owner-only permissions', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({ content: [] }), identity: IDENTITY });
+        expect(statSync(endpoint.address).mode & 0o777).toBe(0o600);
+        expect(statSync(endpoint.presencePath).mode & 0o777).toBe(0o600);
+    });
+});
+// ---------------------------------------------------------------------------
+// presence records
+// ---------------------------------------------------------------------------
+describe('presence records', () => {
+    posixOnly('publishes this session and picks it up again', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({}), identity: IDENTITY });
+        const records = listSessionRecords();
+        expect(records).toHaveLength(1);
+        expect(records[0].pid).toBe(process.pid);
+        expect(records[0].address).toBe(endpoint.address);
+        expect(records[0].shortId).toBeUndefined();
+    });
+    posixOnly('carries the ids once refresh supplies them', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({}), identity: IDENTITY });
+        await endpoint.refresh({ sessionId: 'full-uuid', shortId: 'abcd1234' });
+        expect(listSessionRecords()[0].shortId).toBe('abcd1234');
+        expect(listSessionRecords()[0].sessionId).toBe('full-uuid');
+    });
+    posixOnly('drops a record whose process is gone, and its socket with it', async () => {
+        mkdirSync(getEndpointsDir(), { recursive: true });
+        const deadPid = 2; // pid 2 is not a devharness session on any machine this runs on
+        const deadSocket = join(getEndpointsDir(), '999999.sock');
+        writeFileSync(deadSocket, '');
+        writeFileSync(join(getEndpointsDir(), '999999.json'), JSON.stringify({
+            pid: 999999, ppid: deadPid, cwd: '/gone', address: deadSocket, startedAt: 1,
+        }));
+        expect(listSessionRecords()).toEqual([]);
+        expect(existsSync(join(getEndpointsDir(), '999999.json'))).toBe(false);
+        expect(existsSync(deadSocket)).toBe(false);
+    });
+    posixOnly('ignores a file that is not one of ours', async () => {
+        mkdirSync(getEndpointsDir(), { recursive: true });
+        // The shape server-claims.ts writes - no address, so nothing to dial.
+        writeFileSync(join(getEndpointsDir(), '4242.json'), JSON.stringify({
+            supervisorPid: 4242, cwd: '/repo', childPid: 4243,
+        }));
+        expect(listSessionRecords()).toEqual([]);
+        expect(existsSync(join(getEndpointsDir(), '4242.json'))).toBe(true);
+    });
+    posixOnly('removes the record and the socket on close', async () => {
+        endpoint = await startSessionEndpoint({ executeToolCall: async () => ({}), identity: IDENTITY });
+        const { address, presencePath } = endpoint;
+        await endpoint.close();
+        endpoint = null;
+        expect(existsSync(address)).toBe(false);
+        expect(existsSync(presencePath)).toBe(false);
+    });
+});
+//# sourceMappingURL=session-endpoint.test.js.map

package/build/session-endpoint.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-endpoint.test.js","sourceRoot":"","sources":["../src/session-endpoint.test.ts"],"names":[],"mappings":"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"}

package/build/session-events.d.ts

@@ -0,0 +1,28 @@
+/**
+ * One event stream per session.
+ *
+ * Every push event devharness produces - a guard block, an incoming message -
+ * appends one JSON line to `~/.devharness/events/<session>.jsonl`. One file
+ * means one watch: a session arms a single Monitor and receives every kind of
+ * event, including kinds added later, instead of one watch per feature.
+ *
+ * The plugin's SessionStart hook names this path to each session as it starts,
+ * which is what gets the watch armed. Nothing here verifies that a watch
+ * exists: a session with none simply receives nothing, the same as before the
+ * stream existed.
+ */
+export type EventKind = 'block' | 'message';
+export interface SessionEvent {
+    ts: string;
+    kind: EventKind;
+    [key: string]: unknown;
+}
+export declare function getEventsDir(): string;
+export declare function getEventStreamPath(sessionName: string): string;
+/**
+ * Append one event. Failures are logged and swallowed: the stream is a
+ * notification path, and losing a line must not fail the operation that
+ * produced it.
+ */
+export declare function appendEvent(sessionName: string, kind: EventKind, payload: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=session-events.d.ts.map

package/build/session-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-events.d.ts","sourceRoot":"","sources":["../src/session-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE5C,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/build/session-events.js

@@ -0,0 +1,38 @@
+/**
+ * One event stream per session.
+ *
+ * Every push event devharness produces - a guard block, an incoming message -
+ * appends one JSON line to `~/.devharness/events/<session>.jsonl`. One file
+ * means one watch: a session arms a single Monitor and receives every kind of
+ * event, including kinds added later, instead of one watch per feature.
+ *
+ * The plugin's SessionStart hook names this path to each session as it starts,
+ * which is what gets the watch armed. Nothing here verifies that a watch
+ * exists: a session with none simply receives nothing, the same as before the
+ * stream existed.
+ */
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { getOutputPath } from './helpers/paths.js';
+export function getEventsDir() {
+    return getOutputPath('events', { global: true });
+}
+export function getEventStreamPath(sessionName) {
+    return join(getEventsDir(), `${sessionName}.jsonl`);
+}
+/**
+ * Append one event. Failures are logged and swallowed: the stream is a
+ * notification path, and losing a line must not fail the operation that
+ * produced it.
+ */
+export async function appendEvent(sessionName, kind, payload) {
+    const event = { ts: new Date().toISOString(), kind, ...payload };
+    try {
+        await fs.mkdir(getEventsDir(), { recursive: true });
+        await fs.appendFile(getEventStreamPath(sessionName), JSON.stringify(event) + '\n');
+    }
+    catch (error) {
+        console.error(`[devharness] Failed to append ${kind} event: ${error}`);
+    }
+}
+//# sourceMappingURL=session-events.js.map

package/build/session-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-events.js","sourceRoot":"","sources":["../src/session-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAUnD,MAAM,UAAU,YAAY;IAC1B,OAAO,aAAa,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO,IAAI,CAAC,YAAY,EAAE,EAAE,GAAG,WAAW,QAAQ,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,WAAmB,EACnB,IAAe,EACf,OAAgC;IAEhC,MAAM,KAAK,GAAiB,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;IAC/E,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,MAAM,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IACrF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,iCAAiC,IAAI,WAAW,KAAK,EAAE,CAAC,CAAC;IACzE,CAAC;AACH,CAAC"}

package/build/session-events.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for the per-session event stream.
+ *
+ * The property worth pinning is that every kind lands in one file: a session
+ * arms one watch, and a kind added later arrives on it without a second one.
+ */
+export {};
+//# sourceMappingURL=session-events.test.d.ts.map

package/build/session-events.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-events.test.d.ts","sourceRoot":"","sources":["../src/session-events.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/build/session-events.test.js

@@ -0,0 +1,56 @@
+/**
+ * Tests for the per-session event stream.
+ *
+ * The property worth pinning is that every kind lands in one file: a session
+ * arms one watch, and a kind added later arrives on it without a second one.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, readFileSync, existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { initializePaths } from './helpers/paths.js';
+import { appendEvent, getEventStreamPath, getEventsDir, } from './session-events.js';
+let dir;
+let previousDir;
+const SESSION = 'aaaaaaaa';
+function readStream() {
+    const path = getEventStreamPath(SESSION);
+    if (!existsSync(path))
+        return [];
+    return readFileSync(path, 'utf-8')
+        .split('\n')
+        .filter(line => line.trim())
+        .map(line => JSON.parse(line));
+}
+beforeEach(() => {
+    previousDir = process.env.DEVHARNESS_DIR;
+    dir = mkdtempSync(join(tmpdir(), 'devharness-events-'));
+    process.env.DEVHARNESS_DIR = dir;
+    initializePaths();
+});
+afterEach(() => {
+    if (previousDir === undefined)
+        delete process.env.DEVHARNESS_DIR;
+    else
+        process.env.DEVHARNESS_DIR = previousDir;
+    initializePaths();
+    rmSync(dir, { recursive: true, force: true });
+});
+describe('appendEvent', () => {
+    it('writes one line per event, each stamped and kinded', async () => {
+        await appendEvent(SESSION, 'block', { guard: 'port', tool: 'navigate' });
+        await appendEvent(SESSION, 'message', { from: 'bbbbbbbb' });
+        const events = readStream();
+        expect(events.map(e => e.kind)).toEqual(['block', 'message']);
+        expect(events[0]).toMatchObject({ kind: 'block', guard: 'port', tool: 'navigate' });
+        expect(typeof events[0].ts).toBe('string');
+    });
+    it('puts every kind in the one file, so one watch covers them all', async () => {
+        await appendEvent(SESSION, 'block', {});
+        await appendEvent(SESSION, 'message', {});
+        await appendEvent(SESSION, 'block', {});
+        expect(getEventStreamPath(SESSION)).toBe(join(getEventsDir(), 'aaaaaaaa.jsonl'));
+        expect(readStream()).toHaveLength(3);
+    });
+});
+//# sourceMappingURL=session-events.test.js.map

package/build/session-events.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-events.test.js","sourceRoot":"","sources":["../src/session-events.test.ts"],"names":[],"mappings":"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"}