Skip to content

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

12.0 KB
Raw Blame
/**
 * `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');
  });
});