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
/**
* `npm run doctor` contract (#5304).
*
* The probes themselves are thin delegations to helpers that have their own
* tests (`checkNodeVersion`, `commandExists`, `listPendingMigrations`), so what
* is worth pinning here is the part unique to the doctor: its totality. A
* diagnostic that crashes, hangs, or leaks the user's username into the block
* they are about to paste into a bug report is worse than no diagnostic, and
* each of those is a behavior no caller-level test would catch.
*/
import { afterEach, describe, expect, it, vi } from 'vitest';
import { homedir } from 'os';
import { createServer } from 'net';
import {
PROBE_TIMEOUT_MS,
closeProbeResources,
collectFacts,
defaultProbes,
ecosystemPorts,
formatReport,
isPortFree,
pgHostClass,
portBlock,
resolvePgPort,
runDoctor,
runProbe,
summarize,
} from './doctor.js';
const fact = (name, status, { required = true } = {}) => ({ name, status, detail: '', required });
describe('summarize', () => {
it('is ok only when every required fact is available', () => {
expect(summarize([fact('a', 'available'), fact('b', 'available')]).ok).toBe(true);
expect(summarize([fact('a', 'available'), fact('b', 'unavailable')]).ok).toBe(false);
});
it('never lets an optional fact fail the run', () => {
// The cert, gh, the media toolchain and the port block are all reported but
// none of them stops PortOS from booting — see the probe list.
const report = summarize([
fact('postgres', 'available'),
fact('tls-cert', 'unavailable', { required: false }),
fact('ports', 'unavailable', { required: false }),
]);
expect(report.ok).toBe(true);
});
it('is ok on an empty fact list rather than throwing', () => {
expect(summarize([]).ok).toBe(true);
});
});
describe('runProbe', () => {
it('turns a thrown probe into an unavailable fact instead of rejecting', async () => {
const result = await runProbe({
name: 'postgres',
run: () => { throw new Error('connection refused'); },
});
expect(result).toMatchObject({ name: 'postgres', status: 'unavailable', required: true });
expect(result.detail).toContain('connection refused');
});
it('turns a rejected async probe into an unavailable fact', async () => {
const result = await runProbe({ name: 'x', run: async () => { throw new Error('boom'); } });
expect(result.status).toBe('unavailable');
expect(result.detail).toContain('boom');
});
it('times out a probe that never settles rather than hanging the report', async () => {
// Injected time, not a production sleep: the point is the state machine,
// and a real 12s wait in the suite would be the actual defect.
vi.useFakeTimers();
try {
const pending = runProbe({ name: 'hung', timeoutMs: 1_000, run: () => new Promise(() => {}) });
await vi.advanceTimersByTimeAsync(1_000);
const result = await pending;
expect(result.status).toBe('unavailable');
expect(result.detail).toContain('timed out after 1000ms');
} finally {
vi.useRealTimers();
}
});
it('scrubs the home-directory prefix out of the detail it reports', async () => {
// The whole value proposition is a block the user pastes into a bug report,
// and a thrown ENOENT embeds an absolute path — so the username must be
// gone before the fact is built, not at print time.
const home = homedir();
const result = await runProbe({
name: 'deps:server',
run: () => { throw new Error(`ENOENT: no such file ${home}/github.com/example/server/node_modules`); },
});
expect(result.detail).not.toContain(home);
expect(result.detail).toContain('~/github.com/example/server/node_modules');
});
it('defaults a probe to required, and honors an explicit required:false', async () => {
const available = async () => ({ available: true, detail: 'ok' });
expect((await runProbe({ name: 'a', run: available })).required).toBe(true);
expect((await runProbe({ name: 'b', required: false, run: available })).required).toBe(false);
});
it('reports a probe that returns nothing as unavailable with an empty detail', async () => {
const result = await runProbe({ name: 'silent', run: async () => undefined });
expect(result).toMatchObject({ status: 'unavailable', detail: '' });
});
});
describe('collectFacts', () => {
it('keeps probe-list order regardless of completion order, so two runs diff cleanly', async () => {
const slow = { name: 'slow', run: () => new Promise((r) => setTimeout(() => r({ available: true, detail: '' }), 20)) };
const fast = { name: 'fast', run: async () => ({ available: true, detail: '' }) };
const facts = await collectFacts([slow, fast]);
expect(facts.map((f) => f.name)).toEqual(['slow', 'fast']);
});
});
describe('formatReport', () => {
it('names every missing required fact in the closing line', () => {
const out = formatReport(summarize([
fact('postgres', 'unavailable'),
fact('migrations', 'unavailable'),
fact('node', 'available'),
]));
expect(out).toContain('2 required prerequisites unavailable: postgres, migrations');
});
it('marks an unavailable optional fact as a warning, not a failure', () => {
const out = formatReport(summarize([fact('tls-cert', 'unavailable', { required: false })]));
expect(out).toContain('⚠️');
expect(out).not.toContain('❌');
expect(out).toContain('All required prerequisites are available');
});
});
describe('portBlock', () => {
it('returns only the PortOS-owned 5553-5569 block (core + extension band), deduped and sorted', () => {
// PORTS also carries vLLM/SGLang/Tailcat-forward ports the operator starts
// by hand, and lists POSTGRES twice (its own key plus the docker one).
const ports = portBlock();
expect(ports.length).toBeGreaterThan(0);
expect(ports).toEqual([...new Set(ports)].sort((a, b) => a - b));
expect(ports.every((p) => p >= 5553 && p <= 5569)).toBe(true);
expect(ports).toContain(5555);
});
it('includes the PortOS-managed extension-band sidecars (whisper, eidoverse bridge, JEV, llama.cpp)', () => {
// Regression for #8900: these are started by PortOS itself
// (server/services/voice/bootstrap.js, eidoverseHost.js, jev.js), not by
// the operator, and a stale 5553-5561 range made them invisible to
// `npm run doctor`'s occupancy probe.
const ports = portBlock();
expect(ports).toEqual(expect.arrayContaining([5562, 5563, 5566, 5568]));
});
it('excludes operator-run ports outside the PortOS block', () => {
const ports = portBlock();
expect(ports).not.toContain(15555); // Tailcat forward
expect(ports).not.toContain(18020); // vLLM Qwen
expect(ports).not.toContain(18021); // SGLang Qwen
expect(ports).not.toContain(18022); // Fleet LLM queue
});
});
describe('defaultProbes', () => {
it('gives every prerequisite a unique name and a runnable probe', () => {
const probes = defaultProbes();
expect(new Set(probes.map((p) => p.name)).size).toBe(probes.length);
expect(probes.every((p) => typeof p.run === 'function')).toBe(true);
});
it('requires the boot-blocking prerequisites and leaves the rest advisory', () => {
const required = Object.fromEntries(defaultProbes().map((p) => [p.name, p.required]));
// Without these the server cannot start.
expect(required).toMatchObject({
node: true,
'submodule:slashdo': true,
'deps:server': true,
'data:seeded': true,
postgres: true,
'postgres:pgvector': true,
migrations: true,
});
// These do not block boot. `ports` in particular is advisory on purpose: a
// running install legitimately occupies the block, and failing on that
// would make doctor exit 1 on every healthy machine.
expect(required).toMatchObject({ npm: false, ffmpeg: false, gh: false, 'tls-cert': false, ports: false });
});
});
describe('runDoctor', () => {
it('prints parseable JSON and exits 0 when every required fact is available', async () => {
const log = vi.fn();
const result = await runDoctor({
probes: [
{ name: 'node', run: async () => ({ available: true, detail: 'v24' }) },
{ name: 'gh', required: false, run: async () => ({ available: false, detail: 'not authenticated' }) },
],
json: true,
log,
});
expect(result.exitCode).toBe(0);
const printed = JSON.parse(log.mock.calls[0][0]);
expect(printed.ok).toBe(true);
expect(printed.facts).toHaveLength(2);
expect(printed.facts[0]).toEqual({ name: 'node', status: 'available', detail: 'v24', required: true });
});
it('exits 1 when a required fact is unavailable, and still prints the whole report', async () => {
const log = vi.fn();
const result = await runDoctor({
probes: [
{ name: 'postgres', run: async () => ({ available: false, detail: 'unreachable' }) },
{ name: 'node', run: async () => ({ available: true, detail: 'v24' }) },
],
log,
});
expect(result.exitCode).toBe(1);
expect(log.mock.calls[0][0]).toContain('postgres');
expect(log.mock.calls[0][0]).toContain('node');
});
it('bounds a probe that names no timeout, using the default', async () => {
// Asserting on PROBE_TIMEOUT_MS alone would pass with the timeout deleted
// from runProbe entirely — drive the real default instead.
vi.useFakeTimers();
try {
const pending = runProbe({ name: 'hung', run: () => new Promise(() => {}) });
await vi.advanceTimersByTimeAsync(PROBE_TIMEOUT_MS);
expect((await pending).detail).toContain(`timed out after ${PROBE_TIMEOUT_MS}ms`);
} finally {
vi.useRealTimers();
}
});
});
describe('isPortFree', () => {
it('reports a bound port taken and a free one free, and settles either way', async () => {
// The real socket path, not a mock: the failure this guards against is the
// promise never settling (report hangs), which a stubbed net module cannot
// reproduce.
const held = createServer();
await new Promise((resolve) => held.listen(0, '127.0.0.1', resolve));
const { port } = held.address();
try {
expect(await isPortFree(port)).toBe(false);
} finally {
await new Promise((resolve) => held.close(resolve));
}
// Same port, now released.
expect(await isPortFree(port)).toBe(true);
});
it('resolves without waiting for a live connection to drain', async () => {
// isPortFree resolves before close() rather than from its callback: close()
// drains open sockets first, so a client connecting in the listen/close
// window would otherwise hold the whole report open.
const free = await isPortFree(0);
expect(typeof free).toBe('boolean');
});
});
describe('closeProbeResources', () => {
it('is a no-op when no probe ever opened the pool', async () => {
// The common path: every run that never reached the database probes (a
// bare checkout, or an injected probe list) must still exit cleanly.
await expect(closeProbeResources()).resolves.toBe(true);
});
});
describe('Postgres port resolution', () => {
const original = process.env.PGPORT;
afterEach(() => {
if (original === undefined) delete process.env.PGPORT;
else process.env.PGPORT = original;
});
it('falls back to the launch-time port from ecosystem.config.cjs, not a bare 5432', () => {
// db.js defaults PGPORT to 5432, but nothing sets PGPORT outside PM2 and
// ecosystem.config.cjs DEFAULTS TO DOCKER (5561). Guessing 5432 here would
// report a perfectly healthy Docker install as unreachable — the exact
// false alarm this tool exists to prevent.
delete process.env.PGPORT;
expect(resolvePgPort()).toBe(ecosystemPorts().POSTGRES);
});
it('lets an explicit PGPORT in the environment win', () => {
process.env.PGPORT = '15432';
expect(resolvePgPort()).toBe(15432);
});
it('names the host class only — never a host, user, or password', () => {
process.env.PGPORT = '5561';
expect(pgHostClass()).toBe('docker :5561');
process.env.PGPORT = '5432';
expect(pgHostClass()).toBe('system :5432');
});
});