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

9.8 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { EventEmitter } from 'events';

const mockPm2 = vi.hoisted(() => ({
  connect: vi.fn(),
  disconnect: vi.fn(cb => cb(null)),
  start: vi.fn()
}));

vi.mock('pm2', () => ({ default: { custom: function () { return mockPm2; } } }));

const mockSpawn = vi.hoisted(() => vi.fn());
vi.mock('../lib/childProcess.js', async (importOriginal) => ({
  ...(await importOriginal()),
  spawn: mockSpawn,
}));

import { startApp, startWithCommand, execPm2 } from './pm2.js';

// Fake child_process.spawn result: closes with the given exit code on next tick.
function fakeChild(exitCode = 0) {
  const child = new EventEmitter();
  child.stdout = new EventEmitter();
  child.stderr = new EventEmitter();
  queueMicrotask(() => child.emit('close', exitCode));
  return child;
}

describe('PM2 command launch interpreters', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    mockPm2.connect.mockImplementation(callback => callback(null));
    mockPm2.start.mockImplementation((options, callback) => callback(null, options));
    mockSpawn.mockImplementation(() => fakeChild(0));
  });

  it('executes shell-script commands directly instead of parsing them with Node', async () => {
    await startWithCommand(
      'elsewhere-acres-godot',
      '/repo/elsewhere-acres',
      './scripts/game run',
      { autorestart: false }
    );

    expect(mockPm2.start).toHaveBeenCalledWith(expect.objectContaining({
      name: 'elsewhere-acres-godot',
      script: './scripts/game',
      args: ['run'],
      interpreter: 'none',
      autorestart: false
    }), expect.any(Function));
  });

  it('keeps JavaScript entrypoints on PM2\'s Node interpreter', async () => {
    await startWithCommand('web-app', '/repo/web-app', './server.mjs');

    const [options] = mockPm2.start.mock.calls[0];
    expect(options).not.toHaveProperty('interpreter');
  });

  it('honors a runtime memory limit on both command launch paths', async () => {
    await startWithCommand('example-world', '/repo/worlds', 'bun server/server.ts', { maxMemoryRestart: '2G' });
    expect(mockPm2.start.mock.calls[0][0].max_memory_restart).toBe('2G');
    await startWithCommand('example-world', '/repo/worlds', 'bun server/server.ts', {
      maxMemoryRestart: '2G', pm2Home: '/tmp/example-pm2',
    });
    expect(mockSpawn.mock.calls[0][1]).toEqual(expect.arrayContaining(['--max-memory-restart', '2G']));
  });

  it('applies the same direct-execution rule to configured app scripts', async () => {
    await startApp('tooling-app', { script: 'npm', args: 'run dev' });

    expect(mockPm2.start).toHaveBeenCalledWith(expect.objectContaining({
      script: 'npm',
      args: 'run dev',
      interpreter: 'none'
    }), expect.any(Function));
  });

  // PortOS itself runs under PM2, which exports its pm2_env into our
  // environment as lowercase config keys — and the PM2 CLI reads those keys
  // back as config, outranking explicit flags. Unstripped, portos-server's own
  // 4GB `max_memory_restart` reached every app it launched: PM2's memory
  // watchdog then killed a fully loaded 25GB llama-server seconds after each
  // successful start, in a loop that read as "the server won't start".
  describe('inherited PM2 config in the environment', () => {
    afterEach(() => {
      vi.unstubAllEnvs();
    });

    it('strips PM2\'s own config keys before spawning the CLI', async () => {
      vi.stubEnv('max_memory_restart', '4294967296');
      vi.stubEnv('exec_mode', 'cluster_mode');
      vi.stubEnv('watch', 'true');
      // portos-server carries its own V8 heap cap; inherited, it would cap every
      // app PortOS launches — including one whose job is to hold more than that.
      vi.stubEnv('node_args', '--max-old-space-size=3072');

      await execPm2(['start', '/usr/local/bin/llama-server', '--name', 'portos-llama-server']);

      const [, , spawnOpts] = mockSpawn.mock.calls[0];
      expect(spawnOpts.env).not.toHaveProperty('max_memory_restart');
      expect(spawnOpts.env).not.toHaveProperty('exec_mode');
      expect(spawnOpts.env).not.toHaveProperty('watch');
      expect(spawnOpts.env).not.toHaveProperty('node_args');
      expect(spawnOpts.env.PATH).toBe(process.env.PATH);
    });

    it('strips them from a caller-supplied env too, which inherits the same keys', async () => {
      vi.stubEnv('max_memory_restart', '4294967296');

      await execPm2(['jlist'], { env: { ...process.env, PM2_HOME: '/tmp/example-pm2' } });

      const [, , spawnOpts] = mockSpawn.mock.calls[0];
      expect(spawnOpts.env).not.toHaveProperty('max_memory_restart');
      expect(spawnOpts.env.PM2_HOME).toBe('/tmp/example-pm2');
    });
  });

  describe('server secrets in the environment', () => {
    afterEach(() => {
      vi.unstubAllEnvs();
    });

    it('filters them from the Node API start while keeping the app-configured env', async () => {
      vi.stubEnv('PRIVACY_VAULT_KEY', 'vault');
      vi.stubEnv('PGPASSWORD', 'db');
      await startWithCommand('worlds', '/repo/worlds', 'bun server/server.ts', { port: 8940 });
      await startApp('tooling-app', { script: 'npm', env: { PGPASSWORD: 'app-own' } });

      const [command] = mockPm2.start.mock.calls[0];
      expect(command.filter_env).toEqual(expect.arrayContaining(['PRIVACY_VAULT_KEY', 'PGPASSWORD']));
      const [configured] = mockPm2.start.mock.calls[1];
      expect(configured.filter_env).toContain('PGPASSWORD');
      expect(configured.env).toEqual({ PGPASSWORD: 'app-own' });
    });

    it('omits them from the CLI start environment', async () => {
      vi.stubEnv('PRIVACY_VAULT_KEY', 'vault');
      vi.stubEnv('PGPASSWORD', 'db');
      await startWithCommand('worlds', '/repo/worlds', 'bun server/server.ts', { pm2Home: '/tmp/example-pm2' });

      const [, , spawnOpts] = mockSpawn.mock.calls[0];
      expect(spawnOpts.env).not.toHaveProperty('PRIVACY_VAULT_KEY');
      expect(spawnOpts.env).not.toHaveProperty('PGPASSWORD');
      expect(spawnOpts.env.PM2_HOME).toBe('/tmp/example-pm2');
    });
  });

  // Sibling of the leak above, on the app-facing side: PM2 copies the launching
  // process's environment into the child, so portos-server's own PORT reached
  // every managed app it started. An app's env file cannot undo that — neither
  // Bun's `--env-file` nor dotenv overrides an already-set variable — so the app
  // bound PortOS's port and whichever process lost the boot race crashlooped on
  // EADDRINUSE.
  describe('inherited PORT in the environment', () => {
    it('pins the app\'s own port over the inherited one on the Node API path', async () => {
      vi.stubEnv('PORT', '5555');

      await startWithCommand('worlds', '/repo/worlds', 'bun server/server.ts', { port: 8940 });

      const [options] = mockPm2.start.mock.calls[0];
      expect(options.env).toEqual({ PORT: '8940' });
      vi.unstubAllEnvs();
    });

    it('pins the app\'s own port over the inherited one on the CLI path', async () => {
      vi.stubEnv('PORT', '5555');

      await startWithCommand('worlds', '/repo/worlds', 'bun server/server.ts', {
        port: 8940,
        pm2Home: '/tmp/example-pm2'
      });

      const [, , spawnOpts] = mockSpawn.mock.calls[0];
      expect(spawnOpts.env.PORT).toBe('8940');
      vi.unstubAllEnvs();
    });

    // No recorded port means no correct value to pin, so the Node API path must
    // not invent one — PM2 merges `env` over process.env and cannot unset a key.
    it('sets no env override when the caller gives no port', async () => {
      await startWithCommand('worlds', '/repo/worlds', 'bun server/server.ts');

      const [options] = mockPm2.start.mock.calls[0];
      expect(options).not.toHaveProperty('env');
    });

    // buildEnv drops the inherited PORT/HOST on this path, so a port-less app
    // gets a clean environment rather than PortOS's.
    it('leaves no inherited PORT behind on the CLI path when given no port', async () => {
      vi.stubEnv('PORT', '5555');

      await startWithCommand('worlds', '/repo/worlds', 'bun server/server.ts', {
        pm2Home: '/tmp/example-pm2'
      });

      const [, , spawnOpts] = mockSpawn.mock.calls[0];
      expect(spawnOpts.env).not.toHaveProperty('PORT');
      vi.unstubAllEnvs();
    });
  });

  describe('with a custom pm2Home', () => {
    it('starts via the PM2 CLI (not the default-daemon Node API) so the process is visible to CLI-based status/log/delete calls targeting the same home', async () => {
      const result = await startWithCommand(
        'elsewhere-acres-godot',
        '/repo/elsewhere-acres',
        './scripts/game run',
        { autorestart: false, pm2Home: '/tmp/example-pm2' }
      );

      expect(result).toEqual({ success: true });
      expect(mockPm2.start).not.toHaveBeenCalled();
      expect(mockSpawn).toHaveBeenCalledTimes(1);
      const [, spawnArgv, spawnOpts] = mockSpawn.mock.calls[0];
      const pm2Args = spawnArgv.slice(1); // spawnArgv[0] is the local pm2 CLI binary path
      expect(pm2Args).toEqual(expect.arrayContaining([
        'start', './scripts/game', '--name', 'elsewhere-acres-godot',
        '--cwd', '/repo/elsewhere-acres', '--interpreter', 'none', '--no-autorestart',
      ]));
      expect(pm2Args.slice(-2)).toEqual(['--', 'run']);
      expect(spawnOpts.env.PM2_HOME).toBe('/tmp/example-pm2');
    });

    it('rejects when the pm2 CLI exits non-zero', async () => {
      mockSpawn.mockImplementation(() => {
        const child = new EventEmitter();
        child.stdout = new EventEmitter();
        child.stderr = new EventEmitter();
        queueMicrotask(() => {
          child.stderr.emit('data', Buffer.from('pm2 blew up'));
          child.emit('close', 1);
        });
        return child;
      });

      await expect(startWithCommand(
        'elsewhere-acres-godot', '/repo/elsewhere-acres', './scripts/game run',
        { autorestart: false, pm2Home: '/tmp/example-pm2' }
      )).rejects.toThrow(/pm2 blew up|exited with code 1/);
    });
  });
});