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 { describe, it, expect, vi, beforeEach, onTestFinished } from 'vitest';
// server/sockets/apps.js owns three pieces of state no other layer can observe:
// the re-entrancy guard that stops two concurrent git/PM2 mutations of the same
// checkout, the resumable progress buffer a remounting client rehydrates from,
// and the ledger/broadcast/cleanup epilogue that has to run even when the
// underlying service throws. This suite drives the real socket handlers
// (registerAppHandlers) against a fake socket/io so those contracts are pinned
// at the event boundary rather than through the client's mocked socket.
// PortOS-app preflight refusals are deliberately NOT re-covered here — they
// have their own parity suite (services/updatePreflightParity.test.js).
vi.mock('../services/streamingDetect.js', () => ({ streamDetection: vi.fn() }));
vi.mock('../services/appDeployer.js', () => ({ runDeployFlow: vi.fn() }));
vi.mock('../services/updatePreflight.js', () => ({
checkPortosUpdatePreflight: vi.fn(async () => {}),
}));
vi.mock('../services/appUpdater.js', () => ({ updateApp: vi.fn() }));
vi.mock('../services/history.js', () => ({ logAction: vi.fn() }));
vi.mock('../services/apps.js', () => ({
getAppById: vi.fn(),
notifyAppsChanged: vi.fn(),
updateApp: vi.fn(async () => ({})),
}));
vi.mock('../services/pm2Standardizer.js', () => ({
runStandardizeFlow: vi.fn(),
standardizeRefusalFor: vi.fn(() => null),
analyzeApp: vi.fn(),
createGitBackup: vi.fn(async () => ({ success: false, reason: 'No git repository' })),
applyStandardization: vi.fn(),
}));
import * as appsService from '../services/apps.js';
import * as appUpdater from '../services/appUpdater.js';
import * as pm2Standardizer from '../services/pm2Standardizer.js';
import { logAction } from '../services/history.js';
import { checkPortosUpdatePreflight } from '../services/updatePreflight.js';
import { PORTOS_APP_ID } from '../lib/appIdentity.js';
import { __resetAppOperations, registerAppHandlers } from '../sockets/apps.js';
// Two app records pointing at ONE checkout — the case app id alone can't catch.
const APPS = {
'app-a': { id: 'app-a', name: 'Example App A', repoPath: '/repos/shared', type: 'node' },
'app-b': { id: 'app-b', name: 'Example App B', repoPath: '/repos/shared', type: 'node' },
'app-c': { id: 'app-c', name: 'Example App C', repoPath: '/repos/other', type: 'node' },
// PortOS itself: the one update path with an await (the preflight) between
// resolving the app record and starting the run.
[PORTOS_APP_ID]: { id: PORTOS_APP_ID, name: 'PortOS', repoPath: '/repos/portos', type: 'node' },
};
const deferred = () => {
let resolve;
const promise = new Promise((res) => { resolve = res; });
return { promise, resolve };
};
// Fake socket/io. `io.emit` is a real broadcast — every connected client sees
// it — so one bus fans out to each connection opened in a test, while
// `socket.emit` reaches only its own. Both land in that connection's ordered
// log, since the contract under test is which events carry which payloads.
const makeBus = () => {
const sinks = [];
return {
io: { emit: (event, payload) => sinks.forEach((sink) => sink.push({ event, payload })) },
connect: (sink) => sinks.push(sink),
};
};
// A fresh connection on the shared bus, modelling a client (re)mounting.
const connect = (bus) => {
const handlers = new Map();
const emitted = [];
bus.connect(emitted);
const socket = { on: (event, fn) => handlers.set(event, fn), emit: (event, payload) => emitted.push({ event, payload }) };
registerAppHandlers(socket, bus.io);
return {
emitted,
fire: (event, payload) => handlers.get(event)(payload),
events: (name) => emitted.filter((e) => e.event === name),
last: (name) => emitted.filter((e) => e.event === name).at(-1),
};
};
// Starts an app:update that parks inside appUpdater.updateApp until the caller
// releases it, so the operation is provably in-flight when the next event fires.
// activeAppOperations is module state that outlives the test, so the parked run
// is always released at teardown — otherwise one failing assertion here would
// leave the guard armed and cascade into every later test in the file.
const startParkedUpdate = async (bus, appId, { onEmit } = {}) => {
const entered = deferred();
const gate = deferred();
appUpdater.updateApp.mockImplementation(async (app, emit) => {
onEmit?.(emit);
entered.resolve();
return gate.promise;
});
const client = connect(bus);
const settled = client.fire('app:update', { appId });
const release = (result) => gate.resolve(result ?? { success: true, steps: [] });
onTestFinished(async () => { release(); await settled; });
await entered.promise;
return { client, settled, release };
};
describe('app socket handlers', () => {
let bus;
beforeEach(() => {
vi.clearAllMocks();
// activeAppOperations is module state: a test that fails mid-run would
// otherwise leave the guard armed and cascade into every later test.
__resetAppOperations();
bus = makeBus();
appsService.getAppById.mockImplementation(async (id) => APPS[id] ?? null);
});
describe('in-flight collision guard', () => {
it('refuses a second update for the same app while one is running', async () => {
const { client, settled, release } = await startParkedUpdate(bus, 'app-a');
const second = connect(bus);
await second.fire('app:update', { appId: 'app-a' });
expect(second.last('app:update:error').payload).toMatchObject({
appId: 'app-a',
duplicate: true,
message: 'An update is already running for Example App A',
});
expect(appUpdater.updateApp).toHaveBeenCalledTimes(1);
release();
await settled;
expect(client.last('app:operations:active').payload.operations).toEqual([]);
});
it('refuses an update for a different app record sharing the same repoPath', async () => {
const { settled, release } = await startParkedUpdate(bus, 'app-a');
const other = connect(bus);
await other.fire('app:update', { appId: 'app-b' });
// app-b has no operation of its own — only the shared checkout collides.
expect(other.last('app:update:error').payload).toMatchObject({
appId: 'app-b',
duplicate: true,
message: 'An update is already running for Example App A',
});
expect(appUpdater.updateApp).toHaveBeenCalledTimes(1);
// An unrelated checkout is unaffected by the guard.
const unrelated = connect(bus);
appUpdater.updateApp.mockResolvedValueOnce({ success: true, steps: [] });
await unrelated.fire('app:update', { appId: 'app-c' });
expect(unrelated.events('app:update:error')).toHaveLength(0);
release();
await settled;
});
it("refuses a second self-update dispatched inside the preflight window", async () => {
// app:update awaits the PortOS preflight between resolving the app record
// and starting the run. The claim has to be taken synchronously with the
// conflict check and ahead of that await — otherwise both dispatches pass
// the guard, two update.sh runs rewrite one checkout, and the first to
// finish deletes the survivor from the registry (#6638).
const preflight = deferred();
checkPortosUpdatePreflight.mockImplementation(async () => { await preflight.promise; });
const gate = deferred();
appUpdater.updateApp.mockImplementation(async () => gate.promise);
const first = connect(bus);
const second = connect(bus);
const firstRun = first.fire("app:update", { appId: PORTOS_APP_ID });
const secondRun = second.fire("app:update", { appId: PORTOS_APP_ID });
// Both handlers are now parked in the preflight — the exact window the
// claim used to sit behind. Releasing it lets them race.
preflight.resolve();
await new Promise((resolve) => setTimeout(resolve, 0));
expect(appUpdater.updateApp).toHaveBeenCalledTimes(1);
const refusals = [...first.events("app:update:error"), ...second.events("app:update:error")];
expect(refusals).toHaveLength(1);
expect(refusals[0].payload).toMatchObject({ appId: PORTOS_APP_ID, duplicate: true });
// The survivor is still the only registered run while it is in flight.
expect(first.last("app:operations:active").payload.operations)
.toMatchObject([{ appId: PORTOS_APP_ID, type: "update" }]);
gate.resolve({ success: true, steps: [] });
await Promise.all([firstRun, secondRun]);
expect(first.last("app:operations:active").payload.operations).toEqual([]);
});
it("clears every key a finished operation held without evicting a concurrent run", async () => {
// app-a holds two keys: its own id and the /repos/shared checkout.
const shared = await startParkedUpdate(bus, "app-a");
const unrelated = await startParkedUpdate(bus, "app-c");
shared.release();
await shared.settled;
// A finished run must not take its neighbour out of the registry with it.
expect(unrelated.client.last("app:operations:active").payload.operations)
.toMatchObject([{ appId: "app-c", type: "update" }]);
// ...and it has to release the repoPath key too, or the shared checkout
// stays blocked forever by an operation that already ended.
const reuse = connect(bus);
appUpdater.updateApp.mockResolvedValueOnce({ success: true, steps: [] });
await reuse.fire("app:update", { appId: "app-b" });
expect(reuse.events("app:update:error")).toHaveLength(0);
unrelated.release();
await unrelated.settled;
});
it('refuses a standardize while an update is running on the same checkout', async () => {
const { settled, release } = await startParkedUpdate(bus, 'app-a');
const other = connect(bus);
await other.fire('app:standardize', { appId: 'app-b' });
expect(other.last('app:standardize:error').payload).toMatchObject({
appId: 'app-b',
duplicate: true,
message: 'An update is already running for Example App A',
});
expect(pm2Standardizer.analyzeApp).not.toHaveBeenCalled();
release();
await settled;
});
});
describe('active-operations buffer', () => {
it('replays the in-flight operation to a reconnecting client with repoPath stripped and steps deduped', async () => {
const { settled, release } = await startParkedUpdate(bus, 'app-a', {
onEmit: (emit) => {
emit('pull', 'running', 'Pulling...');
emit('pull', 'done', 'Pulled 3 commits');
emit('install', 'running', 'Installing...');
},
});
// A remount is a brand-new connection: the handler pushes the buffer at
// registration time, and again on demand.
const remount = connect(bus);
remount.fire('app:operations:list');
const [onConnect, onDemand] = remount.events('app:operations:active');
expect(onDemand.payload).toEqual(onConnect.payload);
const [operation, ...rest] = onConnect.payload.operations;
expect(rest).toEqual([]);
expect(operation).toMatchObject({ appId: 'app-a', appName: 'Example App A', type: 'update' });
// repoPath is a server-side detail and must never reach a client payload.
expect(operation).not.toHaveProperty('repoPath');
// Last-write-wins per step id, not one frame appended per emit.
expect(operation.steps.map((s) => [s.step, s.status])).toEqual([
['pull', 'done'],
['install', 'running'],
]);
release();
await settled;
expect(remount.last('app:operations:active').payload.operations).toEqual([]);
});
});
describe('PortOS self-update handoff', () => {
it('keeps the operation live and reports no completion once update.sh owns the restart', async () => {
// update.sh pm2-deletes THIS process partway through, so appUpdater
// returns as soon as the detached script is launched. Reporting the
// operation "complete" here would clear the Git tab's progress row while
// the script is still running, and clearing the operation would drop the
// remaining STEP: frames on the floor — which is the "Stopping PortOS
// apps..." freeze this handoff exists to fix.
appUpdater.updateApp.mockResolvedValue({
success: true,
selfUpdateStarted: true,
steps: [{ step: 'git-pull', success: true }, { step: 'app-update', success: true }],
});
const client = connect(bus);
await client.fire('app:update', { appId: 'app-a' });
expect(client.events('app:update:complete')).toHaveLength(0);
expect(client.events('app:update:error')).toHaveLength(0);
// The launch itself succeeded, so the ledger records it rather than
// waiting for a completion that will never arrive.
expect(logAction).toHaveBeenCalledWith(
'update', 'app-a', 'Example App A',
{ steps: [{ step: 'git-pull', success: true }, { step: 'app-update', success: true }] },
true, null,
);
expect(client.last('app:operations:active').payload.operations).toMatchObject([
{ appId: 'app-a', type: 'update' },
]);
// Nothing ends this operation in production either — the process is
// replaced. Without a process boundary the module state would leak into
// every later test in the file.
__resetAppOperations();
});
it('threads the PortOS preflight acknowledgements into the updater', async () => {
// The launcher re-checks the image guard after taking the lock, so an
// acknowledgement the user opted into here has to reach it or the retry
// refuses again on the very guard they just acknowledged.
appUpdater.updateApp.mockResolvedValue({ success: true, steps: [] });
const client = connect(bus);
await client.fire('app:update', {
appId: 'app-a',
acknowledgeFork: true,
acknowledgePersistentMindImageBackup: true,
});
expect(appUpdater.updateApp).toHaveBeenCalledWith(
APPS['app-a'],
expect.any(Function),
{ syncFork: false, acknowledgeFork: true, acknowledgePersistentMindImageBackup: true },
);
});
});
describe('failure recovery', () => {
it('records a failed update in the ledger, broadcasts the change, and clears the operation', async () => {
appUpdater.updateApp.mockRejectedValue(Object.assign(new Error('git pull failed'), { context: { token: 'do-not-export' } }));
const client = connect(bus);
await client.fire('app:update', { appId: 'app-a' });
// `code` is always on the envelope — null for a plain failure, set for a
// refusal the panel can offer an acknowledgement for.
expect(client.last('app:update:error').payload).toEqual({ appId: 'app-a', code: null, message: 'git pull failed' });
// A thrown update still gets a history row rather than vanishing from it.
expect(logAction).toHaveBeenCalledWith('update', 'app-a', 'Example App A', { steps: [] }, false, 'git pull failed');
expect(appsService.notifyAppsChanged).toHaveBeenCalledWith('update', 'app-a');
// No success/complete frame may follow the failure.
expect(client.events('app:update:complete')).toHaveLength(0);
expect(client.last('app:operations:active').payload.operations).toEqual([]);
});
it.each([
{ credential: 'oauth', command: 'gh auth refresh -h ghe.example.com -s workflow', refreshable: true },
{ credential: 'personal-access-token', command: null, refreshable: false },
{ credential: 'oauth', command: 'gh auth refresh -h ghe.example.com -s workflow', refreshable: false },
])('preserves bounded scope repair and progress for a refused combined update ($credential, $refreshable)', async (guidance) => {
const context = { host: 'ghe.example.com', scopes: ['workflow'], ...guidance };
appUpdater.updateApp.mockImplementation(async (_app, emit) => {
emit('fork-sync', 'running', 'Syncing fork');
throw Object.assign(new Error('workflow scope missing'), {
code: 'FORGE_TOKEN_SCOPE_MISSING', context: { ...context, token: 'do-not-export', raw: { private: true } },
});
});
const client = connect(bus);
await client.fire('app:update', { appId: 'app-a', syncFork: true });
expect(appUpdater.updateApp).toHaveBeenCalledWith(APPS['app-a'], expect.any(Function), expect.objectContaining({ syncFork: true }));
expect(client.last('app:update:error').payload).toEqual({
appId: 'app-a', code: 'FORGE_TOKEN_SCOPE_MISSING', message: 'workflow scope missing', context,
});
expect(logAction).toHaveBeenCalledWith('update', 'app-a', 'Example App A', {
steps: [expect.objectContaining({ step: 'fork-sync', message: 'Syncing fork' })],
errorCode: 'FORGE_TOKEN_SCOPE_MISSING', errorContext: context,
}, false, 'workflow scope missing');
expect(client.events('app:update:complete')).toHaveLength(0);
expect(client.last('app:operations:active').payload.operations).toEqual([]);
});
it('withholds malformed or oversized scope context from failed operation events and history', async () => {
for (const context of [
{ host: 'ghe.example.com', scopes: 'workflow' },
{ host: 'ghe.example.com', scopes: ['workflow'], command: 'x'.repeat(1025) },
]) {
appUpdater.updateApp.mockRejectedValue(Object.assign(new Error('scope missing'), { code: 'FORGE_TOKEN_SCOPE_MISSING', context }));
const client = connect(bus);
await client.fire('app:update', { appId: 'app-a', syncFork: true });
expect(client.last('app:update:error').payload).toEqual({ appId: 'app-a', code: 'FORGE_TOKEN_SCOPE_MISSING', message: 'scope missing' });
expect(logAction).toHaveBeenLastCalledWith('update', 'app-a', 'Example App A', { steps: [] }, false, 'scope missing');
}
});
it('surfaces a standardize analyze failure as an error step and never reaches apply', async () => {
pm2Standardizer.analyzeApp.mockRejectedValue(new Error('LLM provider unavailable'));
const client = connect(bus);
await client.fire('app:standardize', { appId: 'app-a' });
expect(client.events('app:standardize:step').map((e) => [e.payload.step, e.payload.status])).toEqual([
['analyze', 'running'],
['analyze', 'error'],
]);
expect(client.last('app:standardize:error').payload).toEqual({
appId: 'app-a',
message: 'LLM provider unavailable',
});
expect(pm2Standardizer.applyStandardization).not.toHaveBeenCalled();
expect(client.events('app:standardize:complete')).toHaveLength(0);
expect(client.last('app:operations:active').payload.operations).toEqual([]);
});
it('leaves the app record untouched when standardize fails at the apply stage', async () => {
pm2Standardizer.analyzeApp.mockResolvedValue({
success: true,
proposedChanges: { processes: [{ name: 'example-web' }] },
});
pm2Standardizer.applyStandardization.mockResolvedValue({ success: false, errors: ['ecosystem.config.cjs exists'] });
const client = connect(bus);
await client.fire('app:standardize', { appId: 'app-a' });
expect(client.last('app:standardize:error').payload).toEqual({
appId: 'app-a',
message: 'ecosystem.config.cjs exists',
});
// pm2ProcessNames must not be persisted from a standardization that
// never wrote the config those names describe.
expect(appsService.updateApp).not.toHaveBeenCalled();
expect(client.events('app:standardize:complete')).toHaveLength(0);
expect(client.last('app:operations:active').payload.operations).toEqual([]);
});
});
});