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 } from 'vitest';
import databaseSettings from './lib/databaseSettings.cjs';
import { spawnSync } from 'node:child_process';
import { mkdtempSync, rmSync, writeFileSync, readFileSync } from 'fs';
import { tmpdir } from 'node:os';
import { runInNewContext } from 'node:vm';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';
import {
parseDockerPort,
parseNativePort,
} from './lib/setupDbChoice.js';
const here = dirname(fileURLToPath(import.meta.url));
const setupDbSrc = readFileSync(join(here, 'setup-db.js'), 'utf8');
const dockerComposeSrc = readFileSync(join(here, '..', 'docker-compose.yml'), 'utf8');
const dockerPortBindings = dockerComposeSrc.match(/^ ports:\r?\n((?:^ - .*(?:\r?\n|$))+)/m)?.[1]
?.trim()
.split(/\r?\n/)
.map((binding) => binding.trim());
describe('Docker PostgreSQL host binding', () => {
it('publishes the configured host port on loopback only', () => {
expect(dockerPortBindings).toEqual(['- "127.0.0.1:${PGPORT_DOCKER:-5561}:5432"']);
});
});
describe('setup-db docker-port resolver (success log accuracy)', () => {
it('defaults to 5561 when unset / non-numeric', () => {
expect(parseDockerPort(undefined)).toBe(5561);
expect(parseDockerPort('')).toBe(5561);
expect(parseDockerPort('not-a-port')).toBe(5561);
});
it('honors a configured PGPORT_DOCKER, tolerating whitespace', () => {
expect(parseDockerPort('5599')).toBe(5599);
expect(parseDockerPort(' 6000 ')).toBe(6000);
});
it('native port falls back to 5432 the same way', () => {
expect(parseNativePort(undefined)).toBe(5432);
expect(parseNativePort(' 5433 ')).toBe(5433);
});
it('setup-db.js interpolates the resolved docker port, not a hardcoded 5561', () => {
expect(setupDbSrc).toContain('PostgreSQL ready on port ${PG_PORT_DOCKER}');
expect(setupDbSrc).not.toContain("'✅ PostgreSQL ready on port 5561'");
});
});
describe('native setup inherited endpoint', () => {
it('builds native subprocess settings from native identity, not the active Docker port', () => {
// Execute the real setup configuration boundary without starting its menu,
// probing PostgreSQL, or loading the install's .env.
const start = setupDbSrc.indexOf('const settings =');
const end = setupDbSrc.indexOf('function getMode()');
expect(start).toBeGreaterThan(0);
expect(end).toBeGreaterThan(start);
const configure = (env) => runInNewContext(
setupDbSrc.slice(start, end) + '\nPG_CHILD_ENV',
{ process: { env }, envFile: {}, databaseSettings },
);
expect(configure({ PGPORT: '5570', PORTOS_NATIVE_PGPORT: '5433' }).PGPORT).toBe('5433');
expect(configure({ PGPORT: '5434' }).PGPORT).toBe('5434');
});
});
// Run the actual CLI body with synthetic configuration and subprocesses. No
// imports execute, no install .env is read, and no database can be contacted.
async function runSetup({ mode = 'docker', unavailable, tty = false, nativeReady = true, running = true, hostBinding = '127.0.0.1', hostPort = 5561, dotEnv = {}, exportedMode, exportedEnv = {}, hostAuth = 'ok', pgMissing = false } = {}) {
const clients = [];
const savedEnv = { PGMODE: mode, EXAMPLE_SETTING: 'preserved', ...dotEnv };
const initialEnv = { ...savedEnv };
const calls = [];
const childEnvs = [];
const errors = [];
const logs = [];
const exitSignal = {};
const volumeRecords = ['example persisted record'];
const container = { running, hostBinding, hostPort, volumeRecords };
let recreations = 0;
const configuredHostBinding = dockerPortBindings[0].match(/"([^:]+):/)[1];
let exitCode = 0;
let provisioned = false;
const source = setupDbSrc.replace(/^#!.*\n/, '').replace(/^import .*;\n/gm, '')
.replace('import.meta.url', 'scriptUrl');
try {
await runInNewContext(`(async () => {${source}\n})()`, {
scriptUrl: new URL('./setup-db.js', import.meta.url).href, dirname, join, fileURLToPath,
databaseSettings,
createRequire: () => (name) => {
if (name !== 'pg' || pgMissing) throw new Error("Cannot find module 'pg'");
return { Client: class {
constructor(config) { this.config = config; this.ended = false; clients.push(this); }
async connect() { if (hostAuth === 'unreachable') throw new Error('connect ECONNREFUSED'); if (hostAuth === 'badpass') throw new Error('password authentication failed for user "portos"'); }
async query() { return { rows: hostAuth === 'noschema' ? [] : [{ ok: 1 }] }; }
async end() { this.ended = true; }
} };
},
parseEnvFile: () => savedEnv,
upsertEnvKey: (_path, key, value) => { savedEnv[key] = value; },
createInterface: () => { throw new Error('Setup must not prompt to switch backends'); },
resolveBashBinary: () => 'bash',
process: {
env: { ...(exportedMode === undefined ? {} : { PGMODE: exportedMode }), ...exportedEnv }, platform: 'linux', stdin: { isTTY: tty }, stdout: { isTTY: tty },
exit: (code) => { exitCode = code; throw exitSignal; }
},
console: { log: (message) => logs.push(message), error: (message) => errors.push(message) },
execFileSync: (command, args, options) => {
calls.push([command, ...args]);
childEnvs.push(options?.env);
const invocation = [command, ...args].join(' ');
if (invocation === unavailable) throw new Error('Synthetic unavailable dependency');
if (command === 'psql') return nativeReady || provisioned ? '1\n' : '';
if (command === 'bash' && args[1] === 'setup-native') {
provisioned = true;
return '';
}
if (invocation === 'docker compose ps --format json db') return container.running ? '{"State":"running"}' : '';
if (invocation === 'docker compose up -d db') {
const configuredHostPort = parseDockerPort(savedEnv.PGPORT_DOCKER);
if (container.hostBinding !== configuredHostBinding || container.hostPort !== configuredHostPort) recreations++;
Object.assign(container, { running: true, hostBinding: configuredHostBinding, hostPort: configuredHostPort });
return '';
}
if (invocation.startsWith('docker compose exec -T db psql')) return '1\n';
if (['docker --version', 'docker info', 'docker compose version'].includes(invocation)
|| invocation.startsWith('docker compose exec -T db pg_isready -h 127.0.0.1 -U ')) return '';
throw new Error(`Unexpected synthetic subprocess: ${invocation}`);
}
});
} catch (error) {
if (error !== exitSignal) throw error;
}
expect(savedEnv).toEqual(initialEnv);
return { clients, exitCode, calls, childEnvs, errors, logs, container, volumeRecords, recreations };
}
describe('setup preserves the selected database', () => {
it('gives safe initial selection guidance for unsupported file mode without running setup', async () => {
const result = await runSetup({ mode: 'file' });
expect(result.exitCode).toBe(0);
expect(result.calls).toEqual([]);
expect(result.errors.join('\n')).toContain('UNSUPPORTED for production — PostgreSQL is required');
const guidance = result.logs.join('\n');
expect(guidance).toContain('PGMODE=native or PGMODE=docker');
expect(guidance).toContain('repository-root .env, preserving other settings');
expect(guidance).toContain('Unset a conflicting exported');
expect(guidance).toContain('npm run setup:db');
expect(guidance).toContain('retain the backend holding their records');
expect(guidance).toContain('coordinated maintenance cutover');
expect(guidance).toContain('docs/STORAGE.md#setup-path-npm-run-setupdb');
expect(guidance).not.toMatch(/set-mode|use-native|use-docker/);
});
it.each(['docker --version', 'docker info', 'docker compose version'])(
'fails safely when %s is unavailable despite a healthy native database', async (unavailable) => {
for (const tty of [false, true]) {
const result = await runSetup({ unavailable, tty });
expect(result.exitCode).toBe(1);
expect(result.calls.every(([command]) => command === 'docker')).toBe(true);
expect(result.calls.some((call) => call.includes('up'))).toBe(false);
expect(result.errors.join('\n')).toContain('Restore Docker');
expect(result.errors.join('\n')).toContain('coordinated maintenance cutover');
}
}
);
it('hands Compose the resolved settings on every compose subprocess, not its own .env parse', async () => {
const result = await runSetup({
dotEnv: {
PGUSER: 'example-user',
PGDATABASE: 'example_db',
PGPASSWORD: 'example-pass # local note',
PGPORT_DOCKER: '5599'
}
});
expect(result.exitCode).toBe(0);
const composeEnvs = result.calls
.map((call, i) => (call[0] === 'docker' && call[1] === 'compose' && !['version'].includes(call[2]) ? result.childEnvs[i] : null))
.filter(Boolean);
expect(composeEnvs.length).toBeGreaterThanOrEqual(3); // up, pg_isready, psql
for (const env of composeEnvs) {
expect(env).toMatchObject({
PGUSER: 'example-user',
PGDATABASE: 'example_db',
PGPASSWORD: 'example-pass # local note',
PGPORT_DOCKER: '5599'
});
}
expect(result.calls.flat().join(' ')).not.toContain('example-pass');
expect(result.logs.concat(result.errors).join('\n')).not.toContain('example-pass');
});
it.each([true, false])('succeeds with selected Docker (container running: %s)', async (running) => {
const result = await runSetup({ running });
expect(result.exitCode).toBe(0);
expect(result.calls.every(([command]) => command === 'docker')).toBe(true);
const upIndex = result.calls.findIndex((call) => call.includes('up'));
expect(result.calls[upIndex]).toEqual(['docker', 'compose', 'up', '-d', 'db']);
expect(upIndex).toBeLessThan(result.calls.findIndex((call) => call.includes('pg_isready')));
expect(result.recreations).toBe(0);
expect(result.calls.some((call) => call.includes('pg_isready'))).toBe(true);
expect(result.calls.some((call) => call.includes('psql'))).toBe(true);
});
it('verifies the exact configured host endpoint and closes the connection', async () => {
const result = await runSetup({ dotEnv: { PGHOST: 'db.example.invalid', PGPORT_DOCKER: '5599', PGUSER: 'alice', PGDATABASE: 'exampledb', PGPASSWORD: 'example-secret' } });
expect(result.exitCode).toBe(0);
expect(result.clients).toHaveLength(1);
expect(result.clients[0].config).toMatchObject({ host: 'db.example.invalid', port: 5599, user: 'alice', database: 'exampledb', password: 'example-secret' });
expect(result.clients[0].ended).toBe(true);
});
it.each([
['badpass', 'password authentication failed'],
['unreachable', 'ECONNREFUSED'],
['noschema', 'base schema'],
])('fails setup when container probes pass but host check is %s', async (hostAuth, message) => {
const result = await runSetup({ hostAuth, dotEnv: { PGPASSWORD: 'example-secret' } });
expect(result.exitCode).toBe(1);
expect(result.errors.join('\n')).toContain(message);
expect(result.errors.join('\n')).not.toContain('example-secret');
expect(result.logs.join('\n')).not.toContain('PostgreSQL ready');
expect(result.clients[0].ended).toBe(true);
expect(result.container.volumeRecords).toEqual(['example persisted record']);
});
it('fails with an install hint when the pg driver cannot be resolved', async () => {
const result = await runSetup({ pgMissing: true });
expect(result.exitCode).toBe(1);
expect(result.errors.join('\n')).toContain('npm run install:all');
});
it.each([
{ hostBinding: '0.0.0.0', hostPort: 5561, dotEnv: {} },
{ hostBinding: '127.0.0.1', hostPort: 5561, dotEnv: { PGPORT_DOCKER: '5599' } },
])('reconciles a running container mapping without losing its volume ($hostBinding:$hostPort)', async (configuration) => {
const result = await runSetup(configuration);
expect(result.exitCode).toBe(0);
expect(result.container).toMatchObject({
running: true, hostBinding: '127.0.0.1',
hostPort: parseDockerPort(configuration.dotEnv.PGPORT_DOCKER),
volumeRecords: ['example persisted record'],
});
expect(result.container.volumeRecords).toBe(result.volumeRecords);
expect(result.recreations).toBe(1);
});
it.each([true, false])('fails before readiness when reconciliation fails (running: %s)', async (running) => {
const result = await runSetup({ running, unavailable: 'docker compose up -d db' });
expect(result.exitCode).toBe(1);
expect(result.calls.every(([command]) => command === 'docker')).toBe(true);
expect(result.calls.some((call) => call.includes('pg_isready') || call.includes('psql'))).toBe(false);
expect(result.container.volumeRecords).toEqual(['example persisted record']);
expect(result.errors.join('\n')).toContain('Failed to reconcile');
});
it.each([true, false])('succeeds with explicitly selected native (already ready: %s)', async (nativeReady) => {
const result = await runSetup({ mode: 'native', nativeReady });
expect(result.exitCode).toBe(0);
expect(result.calls.some(([command]) => command === 'docker')).toBe(false);
expect(result.calls.some((call) => call.includes('setup-native'))).toBe(!nativeReady);
});
// The command-boundary contract for #10757: a shell left over from another
// PostgreSQL workflow must not redirect the readiness probe or the bootstrap
// child; TLS/auth settings keep working.
it('drops inherited libpq routing variables from the readiness probe and bootstrap child', async () => {
const result = await runSetup({
mode: 'native', nativeReady: false,
dotEnv: { PGHOST: 'db.example.invalid', PGPORT: '5433' },
exportedEnv: {
PGHOSTADDR: '192.0.2.10', PGSERVICE: 'other', PGSERVICEFILE: '/example/service.conf',
PGOPTIONS: '-c search_path=other', PGSSLMODE: 'verify-full', PGPASSFILE: '/example/pgpass',
},
});
expect(result.exitCode).toBe(0);
const psqlEnvs = result.childEnvs.filter((_, i) => result.calls[i][0] === 'psql');
const bootstrapEnv = result.childEnvs[result.calls.findIndex((call) => call.includes('setup-native'))];
expect(psqlEnvs).toHaveLength(2);
for (const env of [...psqlEnvs, bootstrapEnv]) {
for (const name of ['PGHOSTADDR', 'PGSERVICE', 'PGSERVICEFILE', 'PGOPTIONS']) expect(env).not.toHaveProperty(name);
expect(env).toMatchObject({ PGHOST: 'db.example.invalid', PGPORT: '5433', PGSSLMODE: 'verify-full', PGPASSFILE: '/example/pgpass' });
}
});
it('probes and provisions the endpoint selected in .env, host and port alike', async () => {
const result = await runSetup({
mode: 'native', nativeReady: false,
dotEnv: { PGHOST: 'db.example.invalid', PGPORT: '5433' },
});
expect(result.exitCode).toBe(0);
const probes = result.calls.filter(([command]) => command === 'psql');
expect(probes).toHaveLength(2);
for (const probe of probes) {
expect(probe.slice(probe.indexOf('-h'), probe.indexOf('-h') + 4))
.toEqual(['-h', 'db.example.invalid', '-p', '5433']);
}
const setupIndex = result.calls.findIndex((call) => call.includes('setup-native'));
expect(result.childEnvs[setupIndex]).toMatchObject({ PGHOST: 'db.example.invalid', PGPORT: '5433' });
});
// Pairs with scripts/ecosystemEnv.test.js "mode precedence matches setup" (#10758).
it.each([
['docker', 'native', true],
['native', 'docker', false],
['native', '', true],
])('saved %s with exported %j selects the same backend PM2 does', async (mode, exportedMode, expectNative) => {
const result = await runSetup({ mode, exportedMode, nativeReady: true });
expect(result.exitCode).toBe(0);
expect(result.calls.some(([command]) => command === 'psql')).toBe(expectNative);
expect(result.calls.some(([command]) => command === 'docker')).toBe(!expectNative);
});
});
// Config-only: `docker compose config` never contacts the daemon or mutates a
// container. Skipped when the Compose plugin is not installed.
const composeAvailable = spawnSync('docker', ['compose', 'version'], { stdio: 'ignore' }).status === 0;
describe.skipIf(!composeAvailable)('Compose receives the resolved settings (config only)', () => {
it('process environment overrides the .env interpolation of comments and dollar expressions', () => {
const dir = mkdtempSync(join(tmpdir(), 'portos-compose-'));
try {
writeFileSync(join(dir, 'docker-compose.yml'), dockerComposeSrc);
writeFileSync(join(dir, '.env'), [
'PGUSER=example-user',
'PGDATABASE=example_db',
'PGPASSWORD="example-$PORTOS_PROBE_SUFFIX"',
'PGPORT_DOCKER=5599 # note',
'',
].join('\n'));
const config = (extraEnv) => {
const { PGUSER, PGDATABASE, PGPASSWORD, PGPORT_DOCKER, ...base } = process.env;
const result = spawnSync('docker', ['compose', 'config', '--format', 'json'], {
cwd: dir, encoding: 'utf8', env: { ...base, ...extraEnv }
});
expect(result.status, result.stderr).toBe(0);
return JSON.parse(result.stdout).services.db;
};
// Control: Compose alone expands the dollar expression — the divergence being fixed.
expect(config({}).environment.POSTGRES_PASSWORD).toBe('example-');
const forwarded = config({
PGUSER: 'example-user', PGDATABASE: 'example_db',
PGPASSWORD: 'example-$PORTOS_PROBE_SUFFIX', PGPORT_DOCKER: '5599'
});
expect(forwarded.environment).toMatchObject({
POSTGRES_USER: 'example-user',
POSTGRES_DB: 'example_db',
// `config` re-escapes a literal `$` as `$$`; the container receives one `$`.
POSTGRES_PASSWORD: 'example-$$PORTOS_PROBE_SUFFIX'
});
expect(forwarded.ports[0].published).toBe('5599');
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
});