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 } from 'vitest';
import express from 'express';
import { request } from '../lib/testHelper.js';
import { errorMiddleware } from '../lib/errorHandler.js';
vi.mock('../services/brainStorage.js', () => ({
getAll: vi.fn(),
getById: vi.fn(),
create: vi.fn(),
updateWith: vi.fn(),
remove: vi.fn(),
}));
// The resolver has its own suite (services/threadRefs.test.js) and reaches
// Postgres; here it is a seam so these tests assert the ROUTE's contract.
vi.mock('../services/threadSync.js', () => ({ syncGithubThreads: vi.fn(async () => ({ created: 1 })) }));
vi.mock('../services/threadRefs.js', () => ({ resolveThreadRefs: vi.fn() }));
import * as brainStorage from '../services/brainStorage.js';
import { resolveThreadRefs } from '../services/threadRefs.js';
import threadRoutes from './brainThreads.js';
const THREAD_ID = '11111111-1111-4111-8111-111111111111';
const buildApp = () => {
const app = express();
app.use(express.json());
app.use('/api/brain/threads', threadRoutes);
app.use(errorMiddleware);
return app;
};
// Mirror updateWith's contract against a given "fresh" record: run the route's
// fn, capture the partial updates it produced, and return the merged record (or
// null when the record is gone). `seen.updates` lets a test assert exactly what
// the route asked to persist.
const mockUpdateWith = (freshThread) => {
const seen = { updates: null };
brainStorage.updateWith.mockImplementation(async (type, id, fn) => {
if (!freshThread) return null;
const updates = await fn({ ...freshThread });
seen.updates = updates;
return updates ? { ...freshThread, ...updates } : null;
});
return seen;
};
const baseThread = (overrides = {}) => ({
id: THREAD_ID,
title: 'Renew the domain',
status: 'open',
priority: 'normal',
nextAction: 'Check the registrar',
notes: 'Long markdown body',
waitingOn: '',
dueAt: null,
tags: [],
pinned: false,
refs: [],
source: null,
externalState: 'unknown',
closedAt: null,
createdAt: '2026-09-01T00:00:00.000Z',
updatedAt: '2026-09-01T00:00:00.000Z',
...overrides,
});
describe('Brain Threads routes', () => {
let app;
beforeEach(() => {
vi.clearAllMocks();
resolveThreadRefs.mockResolvedValue([]);
app = buildApp();
});
it('validates explicit sync requests before dispatch and supplies creation defaults', async () => {
const { syncGithubThreads } = await import('../services/threadSync.js');
expect((await request(app).post('/api/brain/threads/sync').send({ appId: 'example-app', source: {} })).status).toBe(400);
expect(syncGithubThreads).not.toHaveBeenCalled();
const result = await request(app).post('/api/brain/threads/sync').send({ appId: 'example-app' });
expect(result.status).toBe(200);
expect(result.body).toEqual({ created: 1 });
expect(syncGithubThreads).toHaveBeenCalledWith({ appId: 'example-app', pinned: false });
});
// ===========================================================================
// CREATE — server-managed fields
// ===========================================================================
it('creates a thread with the defaults the record shape promises', async () => {
brainStorage.create.mockImplementation(async (type, data) => ({ id: THREAD_ID, ...data }));
const res = await request(app).post('/api/brain/threads').send({ title: 'Renew the domain' });
expect(res.status).toBe(201);
expect(brainStorage.create).toHaveBeenCalledWith('threads', expect.objectContaining({
title: 'Renew the domain',
status: 'open',
priority: 'normal',
nextAction: '',
dueAt: null,
tags: [],
pinned: false,
refs: [],
}));
});
it('strips the server-managed fields from a client write', async () => {
// `source`/`externalState`/`closedAt` belong to the auto-ingest sync. A
// client that sets them could forge provenance or backdate a completion.
brainStorage.create.mockImplementation(async (type, data) => ({ id: THREAD_ID, ...data }));
await request(app).post('/api/brain/threads').send({
title: 'Forged',
source: { kind: 'github.issue', key: 'o/r#1' },
externalState: 'closed',
closedAt: '2020-01-01T00:00:00.000Z',
});
const [, persisted] = brainStorage.create.mock.calls[0];
expect(persisted.source).toBeNull();
expect(persisted.externalState).toBe('unknown');
expect(persisted.closedAt).toBeNull();
});
it('stamps closedAt when a thread is born in a terminal status', async () => {
brainStorage.create.mockImplementation(async (type, data) => ({ id: THREAD_ID, ...data }));
await request(app).post('/api/brain/threads').send({ title: 'Already done', status: 'done' });
const [, persisted] = brainStorage.create.mock.calls[0];
expect(persisted.closedAt).toEqual(expect.any(String));
});
it('rejects a thread with no title', async () => {
const res = await request(app).post('/api/brain/threads').send({ status: 'open' });
expect(res.status).toBe(400);
expect(brainStorage.create).not.toHaveBeenCalled();
});
// ===========================================================================
// UPDATE — partial semantics + closedAt lifecycle
// ===========================================================================
it('persists only the keys a partial update names', async () => {
// Defaults-free partial: an omitted key must preserve the stored value
// rather than resetting it to its schema default.
const seen = mockUpdateWith(baseThread({ priority: 'high', tags: ['ops'] }));
const res = await request(app).put(`/api/brain/threads/${THREAD_ID}`)
.send({ nextAction: 'Email the registrar' });
expect(res.status).toBe(200);
expect(seen.updates).toEqual({ nextAction: 'Email the registrar' });
expect(res.body.priority).toBe('high');
expect(res.body.tags).toEqual(['ops']);
});
it('stamps closedAt on the transition into a terminal status', async () => {
const seen = mockUpdateWith(baseThread({ status: 'open', closedAt: null }));
await request(app).put(`/api/brain/threads/${THREAD_ID}`).send({ status: 'done' });
expect(seen.updates.closedAt).toEqual(expect.any(String));
});
it('preserves the original closedAt when a done thread is re-saved', async () => {
// Re-saving a finished thread must not rewrite when it was finished.
const seen = mockUpdateWith(baseThread({ status: 'done', closedAt: '2026-09-02T00:00:00.000Z' }));
await request(app).put(`/api/brain/threads/${THREAD_ID}`).send({ status: 'archived' });
expect(seen.updates.closedAt).toBe('2026-09-02T00:00:00.000Z');
});
it('clears closedAt when a thread is reopened', async () => {
const seen = mockUpdateWith(baseThread({ status: 'done', closedAt: '2026-09-02T00:00:00.000Z' }));
await request(app).put(`/api/brain/threads/${THREAD_ID}`).send({ status: 'open' });
expect(seen.updates.closedAt).toBeNull();
});
it('leaves closedAt untouched when the update does not move the status', async () => {
const seen = mockUpdateWith(baseThread({ status: 'done', closedAt: '2026-09-02T00:00:00.000Z' }));
await request(app).put(`/api/brain/threads/${THREAD_ID}`).send({ title: 'Renamed' });
expect(seen.updates).toEqual({ title: 'Renamed' });
});
it('404s an update against a thread that is gone', async () => {
mockUpdateWith(null);
const res = await request(app).put(`/api/brain/threads/${THREAD_ID}`).send({ title: 'x' });
expect(res.status).toBe(404);
});
// ===========================================================================
// READ
// ===========================================================================
it('hydrates refs on the detail read without mutating the stored array', async () => {
const stored = [{ kind: 'brain.idea', id: 'idea-1', label: 'cached' }];
brainStorage.getById.mockResolvedValue(baseThread({ refs: stored }));
resolveThreadRefs.mockResolvedValue([
{ kind: 'brain.idea', id: 'idea-1', label: 'Live title', url: '/brain/ideas', resolved: true },
]);
const res = await request(app).get(`/api/brain/threads/${THREAD_ID}`);
expect(res.status).toBe(200);
expect(res.body.resolvedRefs[0].label).toBe('Live title');
// The stored array round-trips untouched, so a target this build can't
// resolve is not quietly stripped by the next write.
expect(res.body.refs).toEqual(stored);
});
it('omits the markdown body from list rows', async () => {
brainStorage.getAll.mockResolvedValue([baseThread()]);
const res = await request(app).get('/api/brain/threads');
expect(res.body.threads[0]).not.toHaveProperty('notes');
expect(res.body.threads[0].title).toBe('Renew the domain');
});
it('filters by status, tag, pinned and refKind', async () => {
brainStorage.getAll.mockResolvedValue([
baseThread({ id: 'a', status: 'open', tags: ['ops'], pinned: true, refs: [{ kind: 'github.issue', id: 'https://example.com/1' }] }),
baseThread({ id: 'b', status: 'waiting', tags: ['ops'], pinned: false, refs: [] }),
baseThread({ id: 'c', status: 'open', tags: ['home'], pinned: false, refs: [] }),
]);
const ids = async (qs) => (await request(app).get(`/api/brain/threads${qs}`)).body.threads.map((t) => t.id);
expect(await ids('?status=open')).toEqual(['a', 'c']);
// The working set is one request — a comma list, not the archive filtered client-side.
expect(await ids('?status=open,waiting')).toEqual(['a', 'b', 'c']);
expect((await request(app).get('/api/brain/threads?status=open,bogus')).status).toBe(400);
expect(await ids('?tag=ops')).toEqual(['a', 'b']);
expect(await ids('?pinned=true')).toEqual(['a']);
expect(await ids('?pinned=false')).toEqual(['b', 'c']);
expect(await ids('?refKind=github.issue')).toEqual(['a']);
});
it('searches title, next action and notes with ?q=', async () => {
brainStorage.getAll.mockResolvedValue([
baseThread({ id: 'a', title: 'Renew the domain', notes: '' }),
baseThread({ id: 'b', title: 'Other', nextAction: '', notes: 'registrar paperwork' }),
baseThread({ id: 'c', title: 'Other', nextAction: '', notes: '' }),
]);
const res = await request(app).get('/api/brain/threads?q=REGISTRAR');
expect(res.body.threads.map((t) => t.id)).toEqual(['a', 'b']);
});
it('sorts pinned first, then soonest-due', async () => {
brainStorage.getAll.mockResolvedValue([
baseThread({ id: 'undated', dueAt: null, pinned: false }),
baseThread({ id: 'later', dueAt: '2026-10-01T00:00:00.000Z', pinned: false }),
baseThread({ id: 'sooner', dueAt: '2026-09-20T00:00:00.000Z', pinned: false }),
baseThread({ id: 'pinned', dueAt: null, pinned: true }),
]);
const res = await request(app).get('/api/brain/threads');
expect(res.body.threads.map((t) => t.id)).toEqual(['pinned', 'sooner', 'later', 'undated']);
});
it('keeps a total order when two threads share a due date — including none at all', async () => {
// Regression: two UNDATED threads both key to Infinity, and subtracting
// them yields NaN. A comparator that returns NaN abandons the remaining
// tiebreaks, so the order goes engine-defined — and the pagination slice
// below drops or duplicates rows at its boundary when that happens.
brainStorage.getAll.mockResolvedValue([
baseThread({ id: 'c', dueAt: null, updatedAt: '2026-09-01T00:00:00.000Z' }),
baseThread({ id: 'a', dueAt: null, updatedAt: '2026-09-03T00:00:00.000Z' }),
baseThread({ id: 'b', dueAt: null, updatedAt: '2026-09-02T00:00:00.000Z' }),
]);
const res = await request(app).get('/api/brain/threads');
// Falls through to most-recently-touched, which NaN would have skipped.
expect(res.body.threads.map((t) => t.id)).toEqual(['a', 'b', 'c']);
});
it('returns the paginated envelope only when a pagination param is passed', async () => {
brainStorage.getAll.mockResolvedValue([baseThread({ id: 'a' }), baseThread({ id: 'b' })]);
const plain = await request(app).get('/api/brain/threads');
expect(plain.body).not.toHaveProperty('limit');
expect(plain.body.total).toBe(2);
const paged = await request(app).get('/api/brain/threads?limit=1');
expect(paged.body).toMatchObject({ total: 2, limit: 1, offset: 0 });
expect(paged.body.threads).toHaveLength(1);
});
it('404s a detail read for a thread that does not exist', async () => {
brainStorage.getById.mockResolvedValue(null);
const res = await request(app).get(`/api/brain/threads/${THREAD_ID}`);
expect(res.status).toBe(404);
});
// ===========================================================================
// REFS
// ===========================================================================
it('attaches a ref against the fresh record', async () => {
const seen = mockUpdateWith(baseThread({ refs: [{ kind: 'brain.idea', id: 'idea-1', label: '' }] }));
const res = await request(app).post(`/api/brain/threads/${THREAD_ID}/refs`)
.send({ kind: 'github.issue', id: 'https://github.com/o/r/issues/7', label: 'o/r#7' });
expect(res.status).toBe(201);
expect(seen.updates.refs).toEqual([
{ kind: 'brain.idea', id: 'idea-1', label: '' },
{ kind: 'github.issue', id: 'https://github.com/o/r/issues/7', label: 'o/r#7' },
]);
// Same shape as GET /:id, so the client swaps the open record in place
// instead of paying a second read for the hydrated refs.
expect(Array.isArray(res.body.resolvedRefs)).toBe(true);
});
it('replaces a same-(kind,id) ref in place instead of duplicating it', async () => {
// Attaching twice — a double click, or an attach racing a peer apply — must
// be idempotent in ORDER as well as content, so two peers converge.
const seen = mockUpdateWith(baseThread({
refs: [
{ kind: 'brain.idea', id: 'idea-1', label: 'stale' },
{ kind: 'app', id: 'app-1', label: 'App' },
],
}));
await request(app).post(`/api/brain/threads/${THREAD_ID}/refs`)
.send({ kind: 'brain.idea', id: 'idea-1', label: 'fresh' });
expect(seen.updates.refs).toEqual([
{ kind: 'brain.idea', id: 'idea-1', label: 'fresh' },
{ kind: 'app', id: 'app-1', label: 'App' },
]);
});
it('detaches a ref whose id is a full URL', async () => {
const url = 'https://github.com/o/r/issues/7';
const seen = mockUpdateWith(baseThread({
refs: [{ kind: 'github.issue', id: url, label: '' }, { kind: 'app', id: 'app-1', label: '' }],
}));
const res = await request(app)
.delete(`/api/brain/threads/${THREAD_ID}/refs/github.issue/${encodeURIComponent(url)}`);
expect(res.status).toBe(200);
expect(seen.updates.refs).toEqual([{ kind: 'app', id: 'app-1', label: '' }]);
});
it('canonicalizes a legacy ref kind on write', async () => {
const seen = mockUpdateWith(baseThread());
await request(app).post(`/api/brain/threads/${THREAD_ID}/refs`)
.send({ kind: 'writersRoom', id: 'w1' });
expect(seen.updates.refs[0].kind).toBe('writers-room');
});
it('rejects a ref whose kind is not a slug', async () => {
const res = await request(app).post(`/api/brain/threads/${THREAD_ID}/refs`)
.send({ kind: 'Not A Kind!', id: 'x' });
expect(res.status).toBe(400);
expect(brainStorage.updateWith).not.toHaveBeenCalled();
});
it('accepts a kind this build does not know', async () => {
// Forward compatibility: a peer on newer code syncs a thread naming a kind
// added after this build shipped, and the user must still be able to save
// it. The resolver degrades it at render time instead.
const seen = mockUpdateWith(baseThread());
const res = await request(app).post(`/api/brain/threads/${THREAD_ID}/refs`)
.send({ kind: 'some.future.kind', id: 'x' });
expect(res.status).toBe(201);
expect(seen.updates.refs[0].kind).toBe('some.future.kind');
});
// ===========================================================================
// ATTACH
// ===========================================================================
it('attaches to an existing thread when threadId is given', async () => {
const seen = mockUpdateWith(baseThread());
const res = await request(app).post('/api/brain/threads/attach')
.send({ threadId: THREAD_ID, ref: { kind: 'app', id: 'app-1', label: 'PortOS' } });
expect(res.status).toBe(200);
expect(res.body.created).toBe(false);
expect(seen.updates.refs).toEqual([{ kind: 'app', id: 'app-1', label: 'PortOS' }]);
expect(brainStorage.create).not.toHaveBeenCalled();
});
it('mints a thread and attaches in one call when no threadId is given', async () => {
brainStorage.create.mockImplementation(async (type, data) => ({ id: THREAD_ID, ...data }));
const res = await request(app).post('/api/brain/threads/attach')
.send({ ref: { kind: 'app', id: 'app-1', label: 'PortOS' }, title: 'Ship the app' });
expect(res.status).toBe(201);
expect(res.body.created).toBe(true);
expect(res.body.thread).toMatchObject({
title: 'Ship the app',
status: 'open',
refs: [{ kind: 'app', id: 'app-1', label: 'PortOS' }],
});
});
it('titles a minted thread from the ref when no title is given', async () => {
brainStorage.create.mockImplementation(async (type, data) => ({ id: THREAD_ID, ...data }));
const res = await request(app).post('/api/brain/threads/attach')
.send({ ref: { kind: 'app', id: 'app-1', label: 'PortOS' } });
expect(res.body.thread.title).toBe('PortOS');
});
it('routes /attach to the attach handler, not to /:id', async () => {
// The static route has to mount before `/:id`, or "attach" reads as a
// thread id and every attach 404s.
brainStorage.create.mockImplementation(async (type, data) => ({ id: THREAD_ID, ...data }));
const res = await request(app).post('/api/brain/threads/attach')
.send({ ref: { kind: 'app', id: 'app-1' } });
expect(res.status).toBe(201);
});
it('404s an attach against a thread that is gone', async () => {
mockUpdateWith(null);
const res = await request(app).post('/api/brain/threads/attach')
.send({ threadId: THREAD_ID, ref: { kind: 'app', id: 'app-1' } });
expect(res.status).toBe(404);
});
// ===========================================================================
// DELETE
// ===========================================================================
it('tombstone-deletes so the deletion federates', async () => {
brainStorage.remove.mockResolvedValue({ id: THREAD_ID });
const res = await request(app).delete(`/api/brain/threads/${THREAD_ID}`);
expect(res.status).toBe(200);
expect(brainStorage.remove).toHaveBeenCalledWith('threads', THREAD_ID);
});
it('404s a delete for a thread that does not exist', async () => {
brainStorage.remove.mockResolvedValue(null);
const res = await request(app).delete(`/api/brain/threads/${THREAD_ID}`);
expect(res.status).toBe(404);
});
});