Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { createServer } from 'node:http';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { WebSocketServer } from 'ws';
import {
ITERM_NOTIFICATION,
decodeItermClientMessage,
encodeItermServerMessage,
} from '../lib/itermMessages.js';
import { staticImportClosure } from '../lib/staticImportGraph.js';
import { createItermBridge } from './itermBridge.js';
// A fake iTerm2 API server speaking the same PortOS-authored schema over a
// WebSocket on a temp Unix socket. Every fixture below is invented.
const pane = (uuid, width = 80, height = 24) => ({
session: { uniqueIdentifier: uuid, gridSize: { width, height }, title: `title-${uuid}` },
});
const LAYOUT = {
windows: [
{ windowId: 'win-a', tabs: [{ tabId: 'tab-1', root: { links: [pane('AAAA-1'), { node: { links: [pane('AAAA-2')] } }] } }] },
{ windowId: 'win-b', tabs: [{ tabId: 'tab-2', root: { links: [pane('BBBB-1', 120, 40)] } }] },
],
};
const startFakeIterm = async (socketPath) => {
const state = {
handshakes: [],
requests: [],
sockets: new Set(),
layout: LAYOUT,
screenStartLine: 500,
onGetBuffer: null,
};
const httpServer = createServer();
const wss = new WebSocketServer({ server: httpServer, handleProtocols: (protocols) => (protocols.has('api.iterm2.com') ? 'api.iterm2.com' : false) });
const send = (ws, message) => ws.send(encodeItermServerMessage(message));
wss.on('connection', (ws, req) => {
state.handshakes.push({ headers: req.headers, protocol: ws.protocol });
state.sockets.add(ws);
ws.on('close', () => state.sockets.delete(ws));
ws.on('message', async (data) => {
const msg = decodeItermClientMessage(data);
state.requests.push(msg);
const reply = (body) => send(ws, { id: msg.id, ...body });
if (msg.listSessionsRequest) reply({ listSessionsResponse: state.layout });
else if (msg.notificationRequest) reply({ notificationResponse: { status: 0 } });
else if (msg.variableRequest) {
reply({ variableResponse: { status: 0, values: msg.variableRequest.get.map((name) => JSON.stringify(`${name}-${msg.variableRequest.sessionId}`)) } });
} else if (msg.sendTextRequest) reply({ sendTextResponse: { status: 0 } });
else if (msg.getBufferRequest) {
await state.onGetBuffer?.(ws, msg);
const { lineRange = {} } = msg.getBufferRequest;
const includesHistory = Number.isInteger(lineRange.trailingLines);
const visible = [
{ text: `screen of ${msg.getBufferRequest.session}` },
{ text: '$ ' },
];
const history = includesHistory ? [{ text: `history of ${msg.getBufferRequest.session}` }] : [];
reply({
getBufferResponse: {
status: 0,
contents: [...history, ...visible],
cursor: { x: 2, y: state.screenStartLine + 1 },
numLinesAboveScreen: state.screenStartLine,
windowedCoordRange: {
coordRange: {
start: { x: 0, y: state.screenStartLine - history.length },
end: { x: 0, y: state.screenStartLine + visible.length },
},
},
},
});
}
});
});
await new Promise((done) => httpServer.listen(socketPath, done));
state.notify = (notification) => {
for (const ws of state.sockets) send(ws, { notification });
};
state.dropAll = () => {
for (const ws of state.sockets) ws.terminate();
};
state.close = () => new Promise((done) => {
state.dropAll();
wss.close();
httpServer.close(() => done());
});
state.count = (key) => state.requests.filter((r) => r[key]).length;
return state;
};
const fakeSocket = (name) => {
const events = [];
return {
name,
events,
emit: (event, payload) => events.push([event, payload]),
last: (event) => events.filter(([e]) => e === event).at(-1)?.[1],
all: (event) => events.filter(([e]) => e === event).map(([, p]) => p),
};
};
describe('itermBridge', () => {
let dir;
let fake;
let bridge;
let deps;
beforeEach(async () => {
dir = mkdtempSync(join(tmpdir(), 'it2-'));
// Windows CI has no Unix sockets; a named pipe exercises the same path.
const socketPath = process.platform === 'win32'
? `\\\\.\\pipe\\portos-it2-${process.pid}-${Date.now()}`
: join(dir, 's');
fake = await startFakeIterm(socketPath);
deps = {
socketPath,
enabled: true,
running: true,
auth: vi.fn(async () => ({ cookie: 'cookie-test', key: 'key-test' })),
isRunning: vi.fn(async () => deps.running),
detectInstall: vi.fn(async () => ({ state: 'ready' })),
isFeatureEnabled: vi.fn(async () => deps.enabled),
idleMs: 60,
backoffInitialMs: 20,
backoffMaxMs: 40,
libraryVersion: 'node portos-test',
};
bridge = createItermBridge(deps);
});
afterEach(async () => {
bridge.shutdown();
await fake.close();
rmSync(dir, { recursive: true, force: true });
});
const listAndConnect = async () => {
const socket = fakeSocket('lister');
await bridge.subscribeList(socket);
await vi.waitFor(() => expect(socket.last('iterm:sessions')?.sessions?.[0]?.jobName).toBeTruthy());
return socket;
};
it('makes no connection until a socket subscribes, then handshakes with every required header', async () => {
await bridge.reconcileItermBridge({ reason: 'boot' });
expect(deps.auth).not.toHaveBeenCalled();
expect(fake.handshakes).toHaveLength(0);
await listAndConnect();
expect(fake.handshakes).toHaveLength(1);
const { headers, protocol } = fake.handshakes[0];
expect(protocol).toBe('api.iterm2.com');
expect(headers).toMatchObject({
origin: 'ws://localhost/',
'x-iterm2-library-version': 'node portos-test',
'x-iterm2-disable-auth-ui': 'true',
'x-iterm2-cookie': 'cookie-test',
'x-iterm2-key': 'key-test',
'x-iterm2-advisory-name': 'PortOS',
});
const types = fake.requests.filter((r) => r.notificationRequest && !r.notificationRequest.variableMonitorRequest)
.map((r) => r.notificationRequest.notificationType);
expect(types).toEqual(expect.arrayContaining([
ITERM_NOTIFICATION.NEW_SESSION, ITERM_NOTIFICATION.TERMINATE_SESSION, ITERM_NOTIFICATION.LAYOUT_CHANGE,
]));
// Screen updates are NOT subscribed until someone views a session.
expect(types).not.toContain(ITERM_NOTIFICATION.SCREEN_UPDATE);
});
it('builds its own registry in window → tab → pane order', async () => {
const socket = await listAndConnect();
await vi.waitFor(() => expect(socket.last('iterm:sessions').sessions.every((s) => s.cwd)).toBe(true));
const { sessions, status } = socket.last('iterm:sessions');
expect(status.state).toBe('connected');
expect(sessions.map((s) => [s.id, s.windowIndex, s.tabIndex, s.paneIndex, s.paneCount])).toEqual([
['iterm-AAAA-1', 1, 1, 1, 2],
['iterm-AAAA-2', 1, 1, 2, 2],
['iterm-BBBB-1', 2, 1, 1, 1],
]);
expect(sessions[2]).toMatchObject({ cols: 120, rows: 40, label: 'name-BBBB-1', jobName: 'jobName-BBBB-1', cwd: 'path-BBBB-1' });
});
it('never reaches the PortOS shell registry or the Workspaces grouping', () => {
const here = dirname(fileURLToPath(import.meta.url));
const closure = staticImportClosure(resolve(here, 'itermBridge.js')).files;
expect(closure.has(resolve(here, 'shell.js'))).toBe(false);
expect(closure.has(resolve(here, 'workspaceContext.js'))).toBe(false);
});
it('loads bounded iTerm2 history for each viewer and unsubscribes on last detach', async () => {
await listAndConnect();
const viewerA = fakeSocket('a');
const viewerB = fakeSocket('b');
expect(bridge.attachViewer('iterm-AAAA-2', viewerA)).toMatchObject({ id: 'iterm-AAAA-2', cols: 80, rows: 24 });
await vi.waitFor(() => expect(viewerA.last('iterm:output')?.data).toContain('screen of AAAA-2'));
expect(viewerA.last('iterm:output')).toMatchObject({ reset: true });
expect(viewerA.last('iterm:output').data).toContain('history of AAAA-2');
expect(fake.requests.find((r) => r.getBufferRequest)?.getBufferRequest.lineRange.trailingLines).toBe(5_024);
// Cursor y=501 with row 1 at absolute line 500 → screen row 2, col 3.
expect(viewerA.last('iterm:output').data).toContain('\x1b[2;3H');
const screenSubs = () => fake.requests.filter((r) => r.notificationRequest?.notificationType === ITERM_NOTIFICATION.SCREEN_UPDATE);
expect(screenSubs().map((r) => [r.notificationRequest.session, r.notificationRequest.subscribe])).toEqual([['AAAA-2', true]]);
// A second viewer gets its own scrollback snapshot without a second subscription.
expect(bridge.attachViewer('iterm-AAAA-2', viewerB).bufferedOutput).toContain('screen of AAAA-2');
await vi.waitFor(() => expect(viewerB.last('iterm:output')?.reset).toBe(true));
expect(viewerB.last('iterm:output').data).toContain('history of AAAA-2');
bridge.detachViewer('iterm-AAAA-2', viewerA);
expect(screenSubs()).toHaveLength(1);
bridge.detachViewer('iterm-AAAA-2', viewerB);
await vi.waitFor(() => expect(screenSubs().map((r) => r.notificationRequest.subscribe)).toEqual([true, false]));
});
it('advances live viewer scrollback when iTerm2 scrolls the screen', async () => {
await listAndConnect();
const viewer = fakeSocket('v');
bridge.attachViewer('iterm-AAAA-1', viewer);
await vi.waitFor(() => expect(viewer.last('iterm:output')?.reset).toBe(true));
fake.screenStartLine += 2;
fake.notify({ screenUpdateNotification: { session: 'AAAA-1' } });
await vi.waitFor(() => expect(viewer.last('iterm:output')?.scrollbackRows).toBe(2));
expect(viewer.last('iterm:output').reset).toBeUndefined();
});
it('replaces a viewer snapshot after more rows scroll than its prior screen held', async () => {
await listAndConnect();
const viewer = fakeSocket('v');
bridge.attachViewer('iterm-AAAA-1', viewer);
await vi.waitFor(() => expect(viewer.last('iterm:output')?.reset).toBe(true));
fake.screenStartLine += 25;
fake.notify({ screenUpdateNotification: { session: 'AAAA-1' } });
await vi.waitFor(() => expect(viewer.all('iterm:output').filter((item) => item.reset)).toHaveLength(2));
expect(viewer.last('iterm:output').data).toContain('history of AAAA-1');
});
it('coalesces a burst of screen updates to one in-flight fetch plus one trailing fetch', async () => {
await listAndConnect();
let first = true;
fake.onGetBuffer = () => {
if (!first) return;
first = false;
// Five updates land while the first fetch is still in flight.
for (let i = 0; i < 5; i += 1) fake.notify({ screenUpdateNotification: { session: 'AAAA-1' } });
};
const viewer = fakeSocket('v');
bridge.attachViewer('iterm-AAAA-1', viewer);
await vi.waitFor(() => expect(viewer.all('iterm:output')).toHaveLength(2));
await new Promise((done) => setTimeout(done, 50));
expect(fake.count('getBufferRequest')).toBe(2);
});
it('types byte-exact input in order, only from a viewing socket', async () => {
await listAndConnect();
const viewer = fakeSocket('typist');
expect(bridge.sendInput('iterm-BBBB-1', 'x', viewer)).toBe(false); // not viewing yet
bridge.attachViewer('iterm-BBBB-1', viewer);
const inputs = ['l', 's', '\r', '\x1b[A', '\x03', '\x1b[200~line one\nline two\x1b[201~'];
for (const data of inputs) expect(bridge.sendInput('iterm-BBBB-1', data, viewer)).toBe(true);
await vi.waitFor(() => expect(fake.count('sendTextRequest')).toBe(inputs.length));
expect(fake.requests.filter((r) => r.sendTextRequest).map((r) => [r.sendTextRequest.session, r.sendTextRequest.text]))
.toEqual(inputs.map((text) => ['BBBB-1', text]));
expect(bridge.sendInput('iterm-missing', 'x', viewer)).toBe(false);
});
it('drops a terminated session and tells its viewers', async () => {
const socket = await listAndConnect();
const viewer = fakeSocket('v');
bridge.attachViewer('iterm-AAAA-1', viewer);
fake.notify({ terminateSessionNotification: { sessionId: 'AAAA-1' } });
await vi.waitFor(() => expect(viewer.last('iterm:exit')).toEqual({ id: 'iterm-AAAA-1' }));
expect(socket.last('iterm:sessions').sessions.map((s) => s.id)).toEqual(['iterm-AAAA-2', 'iterm-BBBB-1']);
});
it('clears the registry when iTerm2 goes away and reconnects without ever launching it', async () => {
const socket = await listAndConnect();
const viewer = fakeSocket('v');
bridge.attachViewer('iterm-AAAA-1', viewer);
expect(deps.auth).toHaveBeenCalledTimes(1);
// iTerm2 quits: the socket drops and the running check now says no.
deps.running = false;
fake.dropAll();
await vi.waitFor(() => expect(viewer.last('iterm:exit')).toEqual({ id: 'iterm-AAAA-1' }));
await vi.waitFor(() => expect(socket.last('iterm:sessions').status.state).toBe('not-running'));
expect(socket.last('iterm:sessions').sessions).toEqual([]);
expect(deps.auth).toHaveBeenCalledTimes(1); // no cookie request while not running
// iTerm2 relaunches: the backoff loop reconnects on its own.
deps.running = true;
await vi.waitFor(() => expect(socket.last('iterm:sessions').status.state).toBe('connected'));
expect(deps.auth).toHaveBeenCalledTimes(2);
expect(fake.handshakes).toHaveLength(2);
});
it('reports a static install problem without probing iTerm2 at all', async () => {
deps.detectInstall.mockResolvedValue({ state: 'api-disabled' });
const socket = fakeSocket('lister');
await bridge.subscribeList(socket);
expect(socket.last('iterm:sessions').status.state).toBe('api-disabled');
expect(deps.isRunning).not.toHaveBeenCalled();
expect(deps.auth).not.toHaveBeenCalled();
expect(await bridge.getItermStatus()).toEqual({ state: 'api-disabled', detail: null });
});
it('does not expose the local socket path when a connection fails', async () => {
bridge.shutdown();
const socketPath = process.platform === 'win32'
? '\\\\.\\pipe\\example-user-private-socket'
: join(dir, 'example-user', 'missing.sock');
bridge = createItermBridge({ ...deps, socketPath });
const socket = fakeSocket('lister');
const errorLog = vi.spyOn(console, 'error').mockImplementation(() => {});
await bridge.subscribeList(socket);
await vi.waitFor(async () => expect((await bridge.getItermStatus()).state).toBe('connect-failed'));
expect(await bridge.getItermStatus()).toEqual({
state: 'connect-failed',
detail: 'Local iTerm2 socket connection failed',
});
expect(JSON.stringify(socket.all('iterm:sessions'))).not.toContain(socketPath);
expect(errorLog.mock.calls.some(([message]) => /local socket error \([A-Z0-9_]+\)$/u.test(message))).toBe(true);
expect(JSON.stringify(errorLog.mock.calls)).not.toContain(socketPath);
errorLog.mockRestore();
});
it('disconnects immediately when the feature turns off', async () => {
const socket = await listAndConnect();
deps.enabled = false;
await bridge.reconcileItermBridge({ reason: 'feature-toggle' });
expect(socket.last('iterm:sessions')).toMatchObject({ status: { state: 'disconnected' }, sessions: [] });
await vi.waitFor(() => expect(fake.sockets.size).toBe(0));
});
it('disconnects after the idle window once the last subscriber leaves', async () => {
const socket = await listAndConnect();
await bridge.unsubscribeList(socket);
expect(fake.sockets.size).toBe(1); // still inside the idle window
await vi.waitFor(() => expect(fake.sockets.size).toBe(0));
expect(await bridge.getItermStatus()).toEqual({ state: 'disconnected', detail: null });
});
});