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

34.2 KB
Raw Blame
vi.mock('../../services/appQualityFederation.js', () => ({ exportPortosQuality: vi.fn() }));
import { exportPortosQuality } from '../../services/appQualityFederation.js';
vi.mock('../../services/appQuality.js', () => ({ getAppQualityHistory: vi.fn(async () => ({ points: [], days: 90 })), enrichAppsWithQuality: vi.fn(async apps => apps.map(app => ({ ...app, quality: { score: 75 } }))) }));
vi.mock('../../services/appQualitySnapshotFile.js', () => ({ publishAppQualitySnapshot: vi.fn(async () => ({ published: true, hash: 'abc1234', path: '.quality.json' })) }));
vi.mock('../../services/appLaneHealth.js', () => ({ getAppLaneHealth: vi.fn(async () => ({ available: true, windowDays: 60, lanes: [] })) }));
import { describe, it, expect, vi, beforeEach } from 'vitest';
import express from 'express';
import { execFileSync } from 'child_process';
import { mkdtempSync, rmSync } from 'fs';
import { tmpdir } from 'os';
import { join } from 'path';
import { request } from '../../lib/testHelper.js';
import { errorEvents } from '../../lib/errorHandler.js';
import crudRoutes from './crud.js';
import { enrichAppsWithQuality, getAppQualityHistory } from '../../services/appQuality.js';
import { publishAppQualitySnapshot } from '../../services/appQualitySnapshotFile.js';
import { getAppLaneHealth } from '../../services/appLaneHealth.js';

// Mock the services this router (and its port-config service) touch.
vi.mock('../../services/apps.js', () => ({
  getAllApps: vi.fn(),
  getAppById: vi.fn(),
  createApp: vi.fn(),
  updateApp: vi.fn(),
  deleteApp: vi.fn(),
  archiveApp: vi.fn(),
  unarchiveApp: vi.fn(),
  updateAppLayeredIntelligence: vi.fn(),
  notifyAppsChanged: vi.fn(),
  PORTOS_APP_ID: 'portos-default'
}));

vi.mock('../../services/pm2.js', () => ({
  listProcessesStrict: vi.fn(),
  getAppStatusStrict: vi.fn()
}));

vi.mock('../../services/streamingDetect.js', () => ({
  parseEcosystemFromPath: vi.fn(),
  writeEcosystemPortEdits: vi.fn().mockResolvedValue({ file: 'ecosystem.config.cjs', changed: true, remapApplied: true, applied: [], unapplied: [] }),
}));
vi.mock('../../services/appProcessTypes.js', () => ({
  usesPm2: vi.fn((type) => !new Set(['ios-native', 'macos-native', 'xcode', 'swift']).has(type)),
  NON_PM2_TYPES: new Set(['ios-native', 'macos-native', 'xcode', 'swift'])
}));

vi.mock('../../services/appIconDetect.js', () => ({
  detectAppIcon: vi.fn(),
  getIconContentType: vi.fn(),
  isUsableSvg: vi.fn().mockResolvedValue(true)
}));

vi.mock('../../services/xcodeScripts.js', () => ({
  checkScripts: vi.fn().mockReturnValue({ missing: [], present: [] }),
  XCODE_SCRIPT_NAMES: ['deploy.sh', 'take_screenshots.sh', 'take_screenshots_macos.sh']
}));

import * as appsService from '../../services/apps.js';
import * as pm2Service from '../../services/pm2.js';
import * as streamingDetect from '../../services/streamingDetect.js';

describe('Apps CRUD Routes', () => {
  let app;

  beforeEach(() => {
    app = express();
    app.use(express.json());
    app.use('/api/apps', crudRoutes);
    vi.clearAllMocks();
  });

  it('serves numeric federation before app lookup, validates days and refuses unapproved peers', async () => {
    exportPortosQuality.mockResolvedValue({ schemaVersion: 1, measurements: [] });
    const result = await request(app).get('/api/apps/quality-federation?days=30').set('X-PortOS-Instance-Id', 'peer');
    expect(result.status).toBe(200);
    expect(exportPortosQuality).toHaveBeenCalledWith('peer', 30, {}, undefined, undefined);
    expect(appsService.getAppById).not.toHaveBeenCalled();
    const repository = 'a'.repeat(64);
    expect((await request(app).get(`/api/apps/quality-federation?repository=${repository}`).set('X-PortOS-Instance-Id', 'peer')).status).toBe(200);
    expect(exportPortosQuality).toHaveBeenLastCalledWith('peer', 90, {}, repository, undefined);
    await request(app).get('/api/apps/quality-federation?categories=security,privacy').set('X-PortOS-Instance-Id', 'peer');
    expect(exportPortosQuality).toHaveBeenLastCalledWith('peer', 90, {}, undefined, ['security', 'privacy']);
    expect((await request(app).get('/api/apps/quality-federation?repository=invalid')).status).toBe(400);
    expect((await request(app).get('/api/apps/quality-federation?days=999')).status).toBe(400);
    exportPortosQuality.mockResolvedValue(null);
    const emit = vi.fn();
    app.set('io', { emit });
    const onError = vi.fn();
    errorEvents.on('error', onError);
    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    try {
      const refused = await request(app).get('/api/apps/quality-federation');
      expect(refused.status).toBe(403);
      expect(refused.body.code).toBe('PEER_PULL_FORBIDDEN');
      expect(onError).toHaveBeenCalledWith(expect.objectContaining({
        code: 'PEER_PULL_FORBIDDEN',
        severity: 'warning',
      }), expect.anything());
      expect(emit).toHaveBeenCalledWith('error:occurred', expect.objectContaining({
        code: 'PEER_PULL_FORBIDDEN',
        status: 403,
        severity: 'warning',
      }));
      expect(consoleErrorSpy).not.toHaveBeenCalled();
    } finally {
      errorEvents.off('error', onError);
      consoleErrorSpy.mockRestore();
    }
  });

  // Uniquely pins the on-demand publish route: it lands a snapshot PR for the
  // loaded app regardless of the opt-in toggle, and 404s rather than publishing
  // for a stranger.
  it('publishes a managed app snapshot on demand and 404s for an unknown app', async () => {
    appsService.getAppById.mockResolvedValue({ id: 'app-001', name: 'Example App', repoPath: '/repo/example-app' });
    const published = await request(app).post('/api/apps/app-001/quality-snapshot');
    expect(published.status).toBe(200);
    expect(published.body).toEqual({ success: true, published: true, hash: 'abc1234', path: '.quality.json' });
    expect(publishAppQualitySnapshot).toHaveBeenCalledWith({ id: 'app-001', name: 'Example App', repoPath: '/repo/example-app' });

    publishAppQualitySnapshot.mockResolvedValueOnce({ published: false, reason: 'no-evidence', path: '.quality.json' });
    expect((await request(app).post('/api/apps/app-001/quality-snapshot')).body)
      .toEqual({ success: true, published: false, reason: 'no-evidence', path: '.quality.json' });

    appsService.getAppById.mockResolvedValue(null);
    const missing = await request(app).post('/api/apps/nope/quality-snapshot');
    expect(missing.status).toBe(404);
    expect(publishAppQualitySnapshot).toHaveBeenCalledTimes(2);
  });

  describe('GET /api/apps', () => {
    it('should return list of apps with PM2 status', async () => {
      const mockApps = [
        { id: 'app-001', name: 'Test App', pm2ProcessNames: ['test-app'], repoPath: '/tmp/test' }
      ];
      const mockPm2Processes = [
        { name: 'test-app', status: 'online' }
      ];

      appsService.getAllApps.mockResolvedValue(mockApps);
      pm2Service.listProcessesStrict.mockResolvedValue(mockPm2Processes);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue([]);

      const response = await request(app).get('/api/apps');

      expect(response.status).toBe(200);
      expect(response.body).toHaveLength(1);
      expect(response.body[0].overallStatus).toBe('online');
    });

    it('flags non-git directories with isGitRepo and leaves a missing directory unknown', async () => {
      const plainDir = mkdtempSync(join(tmpdir(), 'portos-plain-'));
      const gitDir = mkdtempSync(join(tmpdir(), 'portos-git-'));
      try {
        execFileSync('git', ['init', '-q'], { cwd: gitDir });
        appsService.getAllApps.mockResolvedValue([
          { id: 'plain', name: 'Plain', repoPath: plainDir, pm2ProcessNames: [] },
          { id: 'repo', name: 'Repo', repoPath: gitDir, pm2ProcessNames: [] },
          { id: 'gone', name: 'Gone', repoPath: join(plainDir, 'missing'), pm2ProcessNames: [] },
        ]);
        pm2Service.listProcessesStrict.mockResolvedValue([]);
        streamingDetect.parseEcosystemFromPath.mockResolvedValue([]);

        const response = await request(app).get('/api/apps');

        const flags = Object.fromEntries(response.body.map(a => [a.id, a.isGitRepo]));
        expect(flags).toEqual({ plain: false, repo: true, gone: undefined });
      } finally {
        rmSync(plainDir, { recursive: true, force: true });
        rmSync(gitDir, { recursive: true, force: true });
      }
    });

    it('returns the nav projection without invoking PM2 enrichment', async () => {
      const mockApps = [{
        id: 'app-001', name: 'Test App', icon: 'package', archived: false, type: 'express',
        repoPath: '/tmp/test', pm2ProcessNames: ['test-app'],
      }];
      appsService.getAllApps.mockResolvedValue(mockApps);

      const response = await request(app).get('/api/apps?view=nav');

      expect(response.status).toBe(200);
      expect(response.body).toEqual([{
        id: 'app-001', name: 'Test App', icon: 'package', archived: false, type: 'express',
      }]);
      expect(pm2Service.listProcessesStrict).not.toHaveBeenCalled();
    });

    it('returns the PM2-backed probe projection without the enriched body', async () => {
      appsService.getAllApps.mockResolvedValue([{
        id: 'app-001', name: 'Test App', icon: 'package', type: 'express',
        uiPort: 5555, apiPort: 5551, pm2ProcessNames: ['test-app'], processes: [],
      }]);
      pm2Service.listProcessesStrict.mockResolvedValue([{ name: 'test-app', status: 'online' }]);

      const response = await request(app).get('/api/apps?view=probe');

      expect(response.status).toBe(200);
      expect(response.body).toEqual([{
        id: 'app-001', name: 'Test App', icon: 'package', overallStatus: 'online',
        uiPort: 5555, apiPort: 5551, type: 'express',
      }]);
      expect(pm2Service.listProcessesStrict).toHaveBeenCalledTimes(1);
      expect(response.body[0].pm2Status).toBeUndefined();
    });

    it('keeps quality reports off peer probes and returns them only for explicit local UI reads', async () => {
      appsService.getAllApps.mockResolvedValue([{ id: 'portos-default', name: 'PortOS', type: 'ios-native', repoPath: '/tmp/test' }]);
      const peer = await request(app).get('/api/apps');
      expect(peer.body[0].quality).toBeUndefined();
      expect(enrichAppsWithQuality).not.toHaveBeenCalled();
      const local = await request(app).get('/api/apps?includeQuality=true');
      expect(local.body[0].quality).toEqual({ score: 75 });
      const invalid = await request(app).get('/api/apps?includeQuality=anything');
      expect(invalid.status).toBe(400);
      const invalidView = await request(app).get('/api/apps?view=anything');
      expect(invalidView.status).toBe(400);
      appsService.getAppById.mockResolvedValue({ id: 'portos-default', name: 'PortOS', type: 'ios-native' });
      const detail = await request(app).get('/api/apps/portos-default?includeQuality=true');
      expect(detail.body.quality).toEqual({ score: 75 });
      const history = await request(app).get('/api/apps/portos-default/quality-history?days=90');
      expect(history.status).toBe(200);
      expect(getAppQualityHistory).toHaveBeenCalledWith({ id: 'portos-default', name: 'PortOS', type: 'ios-native' }, 90);
      expect((await request(app).get('/api/apps/portos-default/quality-history?days=9999')).status).toBe(400);
      // Lane health (#12088) is a forge read on request for the loaded app, never cached on the record.
      const laneHealth = await request(app).get('/api/apps/portos-default/lane-health');
      expect(laneHealth.status).toBe(200);
      expect(laneHealth.body).toEqual({ available: true, windowDays: 60, lanes: [] });
      expect(getAppLaneHealth).toHaveBeenCalledWith({ id: 'portos-default', name: 'PortOS', type: 'ios-native' });
      appsService.getAppById.mockResolvedValueOnce(null);
      expect((await request(app).get('/api/apps/missing/lane-health')).status).toBe(404);
    });

    it('should handle apps with no PM2 processes', async () => {
      const mockApps = [
        { id: 'app-001', name: 'Test App', pm2ProcessNames: [], repoPath: '/tmp/test' }
      ];

      appsService.getAllApps.mockResolvedValue(mockApps);
      pm2Service.listProcessesStrict.mockResolvedValue([]);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue([]);

      const response = await request(app).get('/api/apps');

      expect(response.status).toBe(200);
      expect(response.body[0].overallStatus).toBe('not_started');
    });

    it('reports unknown + degraded (not not_started) when the PM2 read fails', async () => {
      const mockApps = [
        { id: 'app-001', name: 'Test App', pm2ProcessNames: ['test-app'], repoPath: '/tmp/test' }
      ];

      appsService.getAllApps.mockResolvedValue(mockApps);
      // Strict read returns null on a failed PM2 read — must not collapse into
      // a confident "not started."
      pm2Service.listProcessesStrict.mockResolvedValue(null);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue([]);

      const response = await request(app).get('/api/apps');

      expect(response.status).toBe(200);
      expect(response.body[0].overallStatus).toBe('unknown');
      expect(response.body[0].degraded).toBe(true);
      expect(response.body[0].pm2Status['test-app'].status).toBe('unknown');
    });

    it('should return empty array when no apps exist', async () => {
      appsService.getAllApps.mockResolvedValue([]);
      pm2Service.listProcessesStrict.mockResolvedValue([]);

      const response = await request(app).get('/api/apps');

      expect(response.status).toBe(200);
      expect(response.body).toHaveLength(0);
    });
  });

  describe('GET /api/apps/:id', () => {
    it('should return app by ID', async () => {
      const mockApp = {
        id: 'app-001',
        name: 'Test App',
        pm2ProcessNames: ['test-app']
      };
      appsService.getAppById.mockResolvedValue(mockApp);
      pm2Service.getAppStatusStrict.mockResolvedValue({ name: 'test-app', status: 'online' });

      const response = await request(app).get('/api/apps/app-001');

      expect(response.status).toBe(200);
      expect(response.body.id).toBe('app-001');
      expect(response.body.pm2Status).toBeDefined();
    });

    it('returns degraded + unknown when the PM2 status read fails', async () => {
      const mockApp = {
        id: 'app-001',
        name: 'Test App',
        pm2ProcessNames: ['test-app']
      };
      appsService.getAppById.mockResolvedValue(mockApp);
      // Detail endpoint reads per-process status via the strict variant, which
      // returns null on a failed read — must surface as degraded, not collapse
      // into a confident not_started.
      pm2Service.getAppStatusStrict.mockResolvedValue(null);

      const response = await request(app).get('/api/apps/app-001');

      expect(response.status).toBe(200);
      expect(response.body.overallStatus).toBe('unknown');
      expect(response.body.degraded).toBe(true);
    });

    it('should return 404 if app not found', async () => {
      appsService.getAppById.mockResolvedValue(null);

      const response = await request(app).get('/api/apps/app-999');

      expect(response.status).toBe(404);
    });
  });

  describe('POST /api/apps', () => {
    it('should create a new app', async () => {
      const newApp = {
        name: 'New App',
        repoPath: '/path/to/repo'
      };
      appsService.createApp.mockResolvedValue({ id: 'app-001', ...newApp });

      const response = await request(app)
        .post('/api/apps')
        .send(newApp);

      expect(response.status).toBe(201);
      expect(response.body.id).toBe('app-001');
      expect(appsService.createApp).toHaveBeenCalledWith(expect.objectContaining({ name: 'New App' }));
      expect(appsService.notifyAppsChanged).toHaveBeenCalledWith('create', 'app-001');
    });

    it('should return 400 if validation fails', async () => {
      // Missing required fields
      const response = await request(app)
        .post('/api/apps')
        .send({});

      expect(response.status).toBe(400);
    });
  });

  describe('PUT /api/apps/:id', () => {
    it('should update an app', async () => {
      const updates = { name: 'Updated Name' };
      appsService.updateApp.mockResolvedValue({ id: 'app-001', name: 'Updated Name' });

      const response = await request(app)
        .put('/api/apps/app-001')
        .send(updates);

      expect(response.status).toBe(200);
      expect(appsService.updateApp).toHaveBeenCalledWith('app-001', expect.objectContaining({ name: 'Updated Name' }));
      expect(appsService.notifyAppsChanged).toHaveBeenCalledWith('update', 'app-001');
    });

    it('should return 404 if app not found', async () => {
      appsService.updateApp.mockResolvedValue(null);

      const response = await request(app)
        .put('/api/apps/app-999')
        .send({ name: 'Test' });

      expect(response.status).toBe(404);
    });

    it('routes a layeredIntelligence update through the dedicated merge helper (not the shallow updateApp)', async () => {
      appsService.updateApp.mockResolvedValue({ id: 'app-001', name: 'App' });
      appsService.updateAppLayeredIntelligence.mockResolvedValue({ id: 'app-001', layeredIntelligence: { enabled: true, sources: { goals: true } } });

      const response = await request(app)
        .put('/api/apps/app-001')
        .send({ layeredIntelligence: { enabled: true } });

      expect(response.status).toBe(200);
      // The nested config must NOT be passed to the shallow updateApp (which would wipe it)…
      expect(appsService.updateApp).toHaveBeenCalledWith('app-001', expect.not.objectContaining({ layeredIntelligence: expect.anything() }));
      // …it goes through the preserving merge helper instead.
      expect(appsService.updateAppLayeredIntelligence).toHaveBeenCalledWith('app-001', { enabled: true });
      expect(response.body.layeredIntelligence.enabled).toBe(true);
    });

    it('writes changed ports back to the ecosystem config (source of truth)', async () => {
      // repoPath must exist on disk so the pathExists guard passes.
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 5173, uiPort: 5174 };
      appsService.getAppById.mockResolvedValue(mockApp);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({ processes: [{ name: 'a', ports: { api: 5173, ui: 5174 } }] });
      appsService.updateApp.mockResolvedValue({ ...mockApp, apiPort: 6000, uiPort: 6001 });

      const response = await request(app)
        .put('/api/apps/app-001')
        .send({ apiPort: 6000, uiPort: 6001 });

      expect(response.status).toBe(200);
      expect(streamingDetect.writeEcosystemPortEdits).toHaveBeenCalledWith(
        process.cwd(),
        expect.arrayContaining([[5173, 6000], [5174, 6001]]),
        []
      );
    });

    it('does not write to the ecosystem config when no port changed', async () => {
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 5173 };
      appsService.getAppById.mockResolvedValue(mockApp);
      appsService.updateApp.mockResolvedValue({ ...mockApp, name: 'Renamed' });

      await request(app).put('/api/apps/app-001').send({ name: 'Renamed' });

      expect(streamingDetect.writeEcosystemPortEdits).not.toHaveBeenCalled();
    });

    it('persists a shared-value port change via the per-process-targeted rewrite', async () => {
      // uiPort and apiPort both 6000 in the same process block. A value-keyed
      // rewrite can't split them, so the route routes it to the targeted edits
      // (process + label) instead — the edit now persists rather than 422.
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 6000, uiPort: 6000 };
      appsService.getAppById.mockResolvedValue(mockApp);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({ processes: [{ name: 'srv', ports: { api: 6000, ui: 6000 } }] });
      appsService.updateApp.mockResolvedValue({ ...mockApp, uiPort: 7000 });

      const response = await request(app).put('/api/apps/app-001').send({ uiPort: 7000 });

      expect(response.status).toBe(200);
      // Empty value-keyed remap (shared value), one targeted edit.
      expect(streamingDetect.writeEcosystemPortEdits).toHaveBeenCalledWith(
        process.cwd(),
        [],
        [{ processName: 'srv', label: 'ui', oldPort: 6000, newPort: 7000 }]
      );
      expect(appsService.updateApp).toHaveBeenCalled();
    });

    it('persists a request mixing a distinct port (value-keyed) and a shared port (targeted) in one PUT', async () => {
      // devUiPort is distinct (5556) so it goes through the value-keyed remap;
      // apiPort/uiPort share 6000 so the uiPort edit goes through the targeted
      // edits. Both are handed to the single atomic writer in one call.
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 6000, uiPort: 6000, devUiPort: 5556 };
      appsService.getAppById.mockResolvedValue(mockApp);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({
        processes: [
          { name: 'srv', ports: { api: 6000, ui: 6000 } },
          { name: 'srv-ui', ports: { devUi: 5556 } }
        ]
      });
      appsService.updateApp.mockResolvedValue({ ...mockApp, uiPort: 7000, devUiPort: 7001 });

      const response = await request(app)
        .put('/api/apps/app-001')
        .send({ uiPort: 7000, devUiPort: 7001 });

      expect(response.status).toBe(200);
      // One atomic write: devUiPort (distinct) in remap; uiPort (shared) targeted.
      expect(streamingDetect.writeEcosystemPortEdits).toHaveBeenCalledWith(
        process.cwd(),
        [[5556, 7001]],
        [{ processName: 'srv', label: 'ui', oldPort: 6000, newPort: 7000 }]
      );
      expect(appsService.updateApp).toHaveBeenCalled();
    });

    it('rejects (422) a shared-value port change the targeted rewrite cannot apply', async () => {
      // Shared value, but the targeted rewrite finds no matching literal to
      // change (e.g. derived from a const outside the block) → unapplied → 422.
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 6000, uiPort: 6000 };
      appsService.getAppById.mockResolvedValue(mockApp);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({ processes: [{ name: 'srv', ports: { api: 6000, ui: 6000 } }] });
      streamingDetect.writeEcosystemPortEdits.mockResolvedValueOnce({
        file: 'ecosystem.config.cjs', changed: false, remapApplied: false, applied: [],
        unapplied: [{ processName: 'srv', label: 'ui', oldPort: 6000, newPort: 7000 }]
      });

      const response = await request(app).put('/api/apps/app-001').send({ uiPort: 7000 });

      expect(response.status).toBe(422);
      expect(appsService.updateApp).not.toHaveBeenCalled();
    });

    it('ignores a submitted uiPort on a derived (served-by-API) app and pins it to the derived value', async () => {
      // App has an API process + Vite dev UI but no literal ports.ui, so the
      // displayed uiPort is derived (= apiPort). The drawer submits all fields
      // and never syncs the UI field to a changed API field, so a stale/echoed
      // or even hand-typed uiPort can't be distinguished from a deliberate
      // (impossible) independent UI change. The route ignores the submitted
      // value: no config write for the UI port, no 422, and the stored uiPort is
      // pinned to the derived value so it keeps tracking the API port.
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 6000, uiPort: 6000, devUiPort: 5556 };
      appsService.getAppById.mockResolvedValue(mockApp);
      // Parser yields api + devUi only; ui is derived from api (served-by-API).
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({
        processes: [{ name: 'srv', ports: { api: 6000, devUi: 5556 } }]
      });
      appsService.updateApp.mockResolvedValue({ ...mockApp });

      const response = await request(app).put('/api/apps/app-001').send({ uiPort: 7000 });

      expect(response.status).toBe(200);
      // No API port change → no config rewrite for the (ignored) UI port.
      expect(streamingDetect.writeEcosystemPortEdits).not.toHaveBeenCalled();
      // Stored uiPort pinned to the derived value (= unchanged apiPort 6000),
      // NOT the submitted 7000.
      const updateArg = appsService.updateApp.mock.calls[0][1];
      expect(updateArg.uiPort).toBe(6000);
    });

    it('strips the echoed derived uiPort so it is never persisted as an explicit field', async () => {
      // Same served-by-API shape; the modal echoes the derived uiPort (6000)
      // unchanged on a rename. That must NOT 422, but it also must NOT be stored
      // as a STALE explicit uiPort — the route pins it to the current derived
      // value so it keeps tracking apiPort instead of freezing.
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 6000, uiPort: 6000, devUiPort: 5556 };
      appsService.getAppById.mockResolvedValue(mockApp);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({
        processes: [{ name: 'srv', ports: { api: 6000, devUi: 5556 } }]
      });
      appsService.updateApp.mockResolvedValue({ ...mockApp, name: 'Renamed' });

      const response = await request(app)
        .put('/api/apps/app-001')
        .send({ name: 'Renamed', uiPort: 6000 });

      expect(response.status).toBe(200);
      expect(streamingDetect.writeEcosystemPortEdits).not.toHaveBeenCalled();
      // uiPort pinned to the derived value (= unchanged apiPort 6000) so a stale
      // stored value can't survive the merge.
      const updateArg = appsService.updateApp.mock.calls[0][1];
      expect(updateArg.uiPort).toBe(6000);
      expect(updateArg.name).toBe('Renamed');
    });

    it('changing apiPort on a served-by-API app (UI following the new API port) persists the API port and pins uiPort to the new derived value', async () => {
      // Valid combined save: API 6000→7000 with the UI following to 7000 (the
      // derived port tracks the new API port). The apiPort edit persists via the
      // value-keyed rewrite; the stored uiPort is overwritten with the NEW
      // derived value (7000) so a stale 6000 can't survive the updateApp merge
      // and block re-derivation.
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 6000, uiPort: 6000, devUiPort: 5556 };
      appsService.getAppById.mockResolvedValue(mockApp);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({
        processes: [{ name: 'srv', ports: { api: 6000, devUi: 5556 } }]
      });
      appsService.updateApp.mockResolvedValue({ ...mockApp, apiPort: 7000, uiPort: 7000 });

      const response = await request(app)
        .put('/api/apps/app-001')
        .send({ apiPort: 7000, uiPort: 7000 });

      expect(response.status).toBe(200);
      // apiPort (distinct, value-keyed) persisted; uiPort follows → not in remap.
      expect(streamingDetect.writeEcosystemPortEdits).toHaveBeenCalledWith(
        process.cwd(),
        [[6000, 7000]],
        []
      );
      const updateArg = appsService.updateApp.mock.calls[0][1];
      expect(updateArg.uiPort).toBe(7000); // pinned to new derived value
      expect(updateArg.apiPort).toBe(7000);
    });

    it('accepts the common API-only edit (drawer echoes the stale derived uiPort) and pins uiPort to the new API port', async () => {
      // The drawer submits all fields and does NOT sync the UI field when the
      // API field changes, so a normal API-only edit arrives as
      // { apiPort: 7000, uiPort: 6000 (old derived) }. That stale echo must NOT
      // 422 — the API port persists via the value-keyed rewrite and the stored
      // uiPort is pinned to the NEW derived value (7000), not the echoed 6000.
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 6000, uiPort: 6000, devUiPort: 5556 };
      appsService.getAppById.mockResolvedValue(mockApp);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({
        processes: [{ name: 'srv', ports: { api: 6000, devUi: 5556 } }]
      });
      appsService.updateApp.mockResolvedValue({ ...mockApp, apiPort: 7000, uiPort: 7000 });

      const response = await request(app)
        .put('/api/apps/app-001')
        .send({ apiPort: 7000, uiPort: 6000 });

      expect(response.status).toBe(200);
      // API port persisted; the stale echoed UI port is ignored, not remapped.
      expect(streamingDetect.writeEcosystemPortEdits).toHaveBeenCalledWith(
        process.cwd(),
        [[6000, 7000]],
        []
      );
      const updateArg = appsService.updateApp.mock.calls[0][1];
      expect(updateArg.uiPort).toBe(7000); // pinned to NEW derived value, not echoed 6000
      expect(updateArg.apiPort).toBe(7000);
    });

    it('does not reject a non-port edit on an app whose top-level ports are not stored (derived)', async () => {
      // apps.json has no apiPort/uiPort (derived from processes); a rename
      // submits the echoed display values. Those must not read as port changes.
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd() };
      appsService.getAppById.mockResolvedValue(mockApp);
      // Config currently serves these derived ports; the modal echoes them back.
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({ processes: [{ name: 'a', ports: { api: 5555, ui: 5556 } }] });
      appsService.updateApp.mockResolvedValue({ ...mockApp, name: 'Renamed' });

      const response = await request(app)
        .put('/api/apps/app-001')
        .send({ name: 'Renamed', apiPort: 5555, uiPort: 5556 });

      expect(response.status).toBe(200);
      expect(streamingDetect.writeEcosystemPortEdits).not.toHaveBeenCalled();
      expect(appsService.updateApp).toHaveBeenCalled();
    });

    it('rejects (422) when the port literal is not found in the config (changed:false)', async () => {
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 5173 };
      appsService.getAppById.mockResolvedValue(mockApp);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({ processes: [{ name: 'a', ports: { api: 5173 } }] });
      streamingDetect.writeEcosystemPortEdits.mockResolvedValueOnce({ file: 'ecosystem.config.cjs', changed: false, remapApplied: false, applied: [], unapplied: [] });

      const response = await request(app).put('/api/apps/app-001').send({ apiPort: 6000 });

      expect(response.status).toBe(422);
      expect(appsService.updateApp).not.toHaveBeenCalled();
    });

    it('fails the request (and does not update the registry) when the config write throws', async () => {
      const mockApp = { id: 'app-001', name: 'App', type: 'node', repoPath: process.cwd(), apiPort: 5173 };
      appsService.getAppById.mockResolvedValue(mockApp);
      streamingDetect.parseEcosystemFromPath.mockResolvedValue({ processes: [{ name: 'a', ports: { api: 5173 } }] });
      streamingDetect.writeEcosystemPortEdits.mockRejectedValueOnce(new Error('EACCES'));

      const response = await request(app).put('/api/apps/app-001').send({ apiPort: 6000 });

      expect(response.status).toBeGreaterThanOrEqual(500);
      // Registry write must not happen after a failed canonical-config write.
      expect(appsService.updateApp).not.toHaveBeenCalled();
    });
  });

  describe('DELETE /api/apps/:id', () => {
    it('should delete an app', async () => {
      appsService.deleteApp.mockResolvedValue(true);

      const response = await request(app).delete('/api/apps/app-001');

      expect(response.status).toBe(204);
      expect(appsService.deleteApp).toHaveBeenCalledWith('app-001');
      expect(appsService.notifyAppsChanged).toHaveBeenCalledWith('delete', 'app-001');
    });

    it('should return 404 if app not found', async () => {
      appsService.deleteApp.mockResolvedValue(false);

      const response = await request(app).delete('/api/apps/app-999');

      expect(response.status).toBe(404);
    });

    it('should return 403 when deleting PortOS baseline app', async () => {
      const response = await request(app).delete('/api/apps/portos-default');

      expect(response.status).toBe(403);
      expect(appsService.deleteApp).not.toHaveBeenCalled();
    });
  });

  describe('POST /api/apps/:id/archive', () => {
    it('should return 403 when archiving PortOS baseline app', async () => {
      const response = await request(app).post('/api/apps/portos-default/archive');

      expect(response.status).toBe(403);
      expect(appsService.archiveApp).not.toHaveBeenCalled();
    });
  });

  describe('GET /api/apps - devUiPort enrichment', () => {
    it('should include devUiPort derived from process ports.devUi', async () => {
      const mockApps = [{
        id: 'app-001',
        name: 'Test App',
        pm2ProcessNames: ['test-app'],
        repoPath: '/tmp/test',
        processes: [{ name: 'test-app', ports: { devUi: 5554 } }]
      }];
      appsService.getAllApps.mockResolvedValue(mockApps);
      pm2Service.listProcessesStrict.mockResolvedValue([]);

      const response = await request(app).get('/api/apps');

      expect(response.status).toBe(200);
      expect(response.body[0].devUiPort).toBe(5554);
    });

    it('should derive uiPort from apiPort when app has devUi but no ui process', async () => {
      const mockApps = [{
        id: 'app-001',
        name: 'Test App',
        pm2ProcessNames: ['test-api', 'test-ui'],
        repoPath: '/tmp/test',
        processes: [
          { name: 'test-api', ports: { api: 5551 } },
          { name: 'test-ui', ports: { devUi: 5550 } }
        ]
      }];
      appsService.getAllApps.mockResolvedValue(mockApps);
      pm2Service.listProcessesStrict.mockResolvedValue([]);

      const response = await request(app).get('/api/apps');

      expect(response.status).toBe(200);
      expect(response.body[0].uiPort).toBe(5551);
      expect(response.body[0].devUiPort).toBe(5550);
      expect(response.body[0].apiPort).toBe(5551);
    });

    it('should use explicit devUiPort over derived value', async () => {
      const mockApps = [{
        id: 'app-001',
        name: 'Test App',
        pm2ProcessNames: ['test-app'],
        repoPath: '/tmp/test',
        devUiPort: 4444,
        processes: [{ name: 'test-app', ports: { devUi: 5554 } }]
      }];
      appsService.getAllApps.mockResolvedValue(mockApps);
      pm2Service.listProcessesStrict.mockResolvedValue([]);

      const response = await request(app).get('/api/apps');

      expect(response.status).toBe(200);
      expect(response.body[0].devUiPort).toBe(4444);
    });
  });
});