Initial commit — SvelteKit fleet manager for T5 Plutonium servers

Ports push_scripts.sh (1497 lines of bash) to a SvelteKit + SQLite web app
that manages a fleet of T5 Plutonium servers running on Komodo. Same push
and beta workflow as the shell script, with a live SSE pipeline view, a
!rt-token-gated auth modal that hard-pauses deployments on stale tokens,
per-file audit diffs, and a Komodo-container deployment target.

- Push/beta engines port the exact filter, held-by-beta, conflict, and
  stale-backup rules from the shell script
- SQLite (better-sqlite3) replaces script_metadata.json; a one-shot
  importer moves legacy state over on first boot
- 16 vitest tests cover push add/update/skip, beta open→rollback,
  open→promote, conflict guards, sweep frozen/manual branches, and IW4M
  login/status parsing
- docker/ + komodo/stack.toml deploy as a managed container on the same
  host as the game servers, /root/zombies bind-mounted at the same path
  the shell script used

tests/helpers/fixture.ts

@@ -0,0 +1,74 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export interface Fixture {
+    root: string;
+    shared: string;
+    staging: string;
+    t5: string;
+    dbPath: string;
+    cleanup: () => Promise<void>;
+}
+
+/**
+ * Build a zombies/ tree in a temp dir and point env at it BEFORE the code
+ * under test is imported. Returns paths + a cleanup fn.
+ */
+export async function newFixture(files: Record<string, string> = {}, servers: string[] = ['t5_kino_1']): Promise<Fixture> {
+    const root = await mkdtemp(join(tmpdir(), 'cherry-'));
+    const shared = join(root, 'shared/scripts');
+    const staging = join(shared, 'betas');
+    const t5 = join(root, 't5');
+    const dbPath = join(root, 'cherry.db');
+    await mkdir(staging, { recursive: true });
+    await mkdir(t5, { recursive: true });
+
+    for (const [rel, body] of Object.entries(files)) {
+        const p = join(shared, rel);
+        await mkdir(join(p, '..'), { recursive: true });
+        await writeFile(p, body);
+    }
+    for (const s of servers) {
+        await mkdir(join(t5, s, 'runtime/plutonium/storage/t5/raw/scripts/sp'), { recursive: true });
+    }
+
+    process.env.SHARED_SCRIPTS = shared;
+    process.env.SERVERS_ROOT = t5;
+    process.env.REL_DEST = 'runtime/plutonium/storage/t5/raw/scripts/sp';
+    process.env.DB_PATH = dbPath;
+    process.env.DEPLOY_KEEP_DAYS = '7';
+    process.env.HTTP_TIMEOUT_MS = '2000';
+
+    return {
+        root,
+        shared,
+        staging,
+        t5,
+        dbPath,
+        cleanup: async () => {
+            // On Windows the SQLite handle keeps a lock on cherry.db-shm/wal
+            // and rmdir refuses to remove the temp tree. Close the singleton
+            // (if this test imported it) before removing the dir. Fresh
+            // dynamic import so we grab whatever handle the test opened.
+            try {
+                const mod = (await import('../../src/lib/server/db/index.js')) as {
+                    closeDb: () => void;
+                };
+                mod.closeDb();
+            } catch {
+                /* db module was never loaded — nothing to close */
+            }
+            await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+        }
+    };
+}
+
+/**
+ * Fresh module-level state. Vitest caches modules per file — this forces a
+ * re-import so the tests can rebuild the singleton DB handle against a new
+ * fixture.
+ */
+export async function importFresh<T>(mod: string): Promise<T> {
+    return (await import(`${mod}?t=${Date.now()}${Math.random()}`)) as T;
+}

tests/unit/beta.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { newFixture, type Fixture } from '../helpers/fixture.js';
+
+let fixture: Fixture;
+
+beforeEach(async () => {
+    vi.resetModules();
+    fixture = await newFixture(
+        { 'hud.gsc': 'v1', 'zom.gsc': 'v1' },
+        ['t5_kino_1', 't5_ascension_1']
+    );
+});
+
+afterEach(async () => {
+    await fixture.cleanup();
+});
+
+describe('beta lifecycle', () => {
+    it('open → rollback restores original state', async () => {
+        const { doPush } = await import('../../src/lib/server/fleet/push.js');
+        const { openBeta, rollbackBeta } = await import('../../src/lib/server/fleet/beta.js');
+        const { seedServerRegistry } = await import('../../src/lib/server/fleet/servers.js');
+        await seedServerRegistry();
+
+        // Populate servers with v1 first
+        await doPush({ patterns: ['*'] });
+
+        // Stage a new hud
+        await writeFile(join(fixture.staging, 'hud.gsc'), 'v2');
+
+        // Open beta on t5_kino_1 only
+        const opened = await openBeta({ name: 'test1', patterns: ['t5_kino_1'] });
+        expect(opened.slug).toBe('test1');
+        expect(opened.servers).toEqual(['t5_kino_1']);
+
+        // On kino: hud-beta.gsc = v2, hud.OLD = v1, hud.gsc gone
+        const kinoSp = join(fixture.t5, 't5_kino_1', 'runtime/plutonium/storage/t5/raw/scripts/sp');
+        expect(await readFile(join(kinoSp, 'hud-beta.gsc'), 'utf8')).toBe('v2');
+        expect(await readFile(join(kinoSp, 'hud.OLD'), 'utf8')).toBe('v1');
+        expect(existsSync(join(kinoSp, 'hud.gsc'))).toBe(false);
+
+        // ascension untouched
+        const ascSp = join(fixture.t5, 't5_ascension_1', 'runtime/plutonium/storage/t5/raw/scripts/sp');
+        expect(await readFile(join(ascSp, 'hud.gsc'), 'utf8')).toBe('v1');
+
+        // Rollback
+        const back = await rollbackBeta('test1');
+        expect(back.restored).toContain('hud.gsc');
+        expect(await readFile(join(kinoSp, 'hud.gsc'), 'utf8')).toBe('v1');
+        expect(existsSync(join(kinoSp, 'hud-beta.gsc'))).toBe(false);
+        expect(existsSync(join(kinoSp, 'hud.OLD'))).toBe(false);
+    });
+
+    it('open → promote lands the beta on shared/scripts and clears beta files', async () => {
+        const { doPush } = await import('../../src/lib/server/fleet/push.js');
+        const { openBeta, promoteBeta } = await import('../../src/lib/server/fleet/beta.js');
+        const { seedServerRegistry } = await import('../../src/lib/server/fleet/servers.js');
+        await seedServerRegistry();
+
+        await doPush({ patterns: ['*'] });
+        await writeFile(join(fixture.staging, 'hud.gsc'), 'v2');
+        await openBeta({ name: 'promote-me', patterns: ['t5_kino_1'] });
+
+        const kinoSp = join(fixture.t5, 't5_kino_1', 'runtime/plutonium/storage/t5/raw/scripts/sp');
+        expect(existsSync(join(kinoSp, 'hud-beta.gsc'))).toBe(true);
+
+        await promoteBeta('promote-me');
+
+        // shared has v2 now
+        expect(await readFile(join(fixture.shared, 'hud.gsc'), 'utf8')).toBe('v2');
+        // kino has plain hud.gsc = v2, no OLD, no -beta
+        expect(await readFile(join(kinoSp, 'hud.gsc'), 'utf8')).toBe('v2');
+        expect(existsSync(join(kinoSp, 'hud-beta.gsc'))).toBe(false);
+        expect(existsSync(join(kinoSp, 'hud.OLD'))).toBe(false);
+    });
+
+    it('refuses to open a beta whose staged file matches an already-owned target', async () => {
+        const { doPush } = await import('../../src/lib/server/fleet/push.js');
+        const { openBeta, BetaError } = await import('../../src/lib/server/fleet/beta.js');
+        const { seedServerRegistry } = await import('../../src/lib/server/fleet/servers.js');
+        await seedServerRegistry();
+        await doPush({ patterns: ['*'] });
+
+        // First beta claims hud on kino
+        await writeFile(join(fixture.staging, 'hud.gsc'), 'v2');
+        await openBeta({ name: 'first', patterns: ['t5_kino_1'] });
+
+        // Second attempt on kino should conflict
+        await writeFile(join(fixture.staging, 'hud.gsc'), 'v3');
+        await expect(openBeta({ name: 'second', patterns: ['t5_kino_1'] })).rejects.toThrow(BetaError);
+    });
+});

tests/unit/files.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { betaFile, oldFile, slugify } from '../../src/lib/server/fleet/files.js';
+
+describe('slugify', () => {
+    it('matches the shell script behavior', () => {
+        expect(slugify('New HUD Test')).toBe('new-hud-test');
+        expect(slugify('  --Weird!!!  ')).toBe('weird');
+        expect(slugify('t5_kino_1')).toBe('t5-kino-1');
+    });
+});
+
+describe('betaFile', () => {
+    it('inserts -beta before the extension', () => {
+        expect(betaFile('hud.gsc')).toBe('hud-beta.gsc');
+        expect(betaFile('perks/zom.gsc')).toBe('perks/zom-beta.gsc');
+    });
+    it('handles files without extension', () => {
+        expect(betaFile('README')).toBe('README-beta');
+    });
+});
+
+describe('oldFile', () => {
+    it('replaces extension with .OLD', () => {
+        expect(oldFile('hud.gsc')).toBe('hud.OLD');
+        expect(oldFile('perks/zom.gsc')).toBe('perks/zom.OLD');
+    });
+});

tests/unit/iw4m.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { newFixture, type Fixture } from '../helpers/fixture.js';
+
+let fixture: Fixture;
+
+beforeEach(async () => {
+    vi.resetModules();
+    fixture = await newFixture();
+    process.env.IW4M_ADDRESS = 'http://iw4m.test';
+    process.env.IW4M_CLIENT_ID = '1';
+    vi.stubGlobal('fetch', vi.fn());
+});
+
+afterEach(async () => {
+    await fixture.cleanup();
+    vi.unstubAllGlobals();
+});
+
+describe('loginWithToken', () => {
+    it('returns cookie + expiry on 2xx', async () => {
+        (globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce(
+            new Response('', {
+                status: 200,
+                headers: { 'Set-Cookie': '.AspNetCore.Cookies=abc; path=/; httponly' }
+            })
+        );
+        const { loginWithToken } = await import('../../src/lib/server/integrations/iw4m.js');
+        const res = await loginWithToken('abcd');
+        expect(res.ok).toBe(true);
+        if (res.ok) {
+            expect(res.cookie).toContain('.AspNetCore.Cookies=abc');
+            expect(res.expiresAt).toBeGreaterThan(Date.now());
+        }
+    });
+
+    it('returns rejected on 401', async () => {
+        (globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce(new Response('', { status: 401 }));
+        const { loginWithToken } = await import('../../src/lib/server/integrations/iw4m.js');
+        const res = await loginWithToken('abcd');
+        expect(res.ok).toBe(false);
+        if (!res.ok) expect(res.reason).toBe('rejected');
+    });
+
+    it('returns unreachable on network error', async () => {
+        (globalThis.fetch as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('ECONNREFUSED'));
+        const { loginWithToken } = await import('../../src/lib/server/integrations/iw4m.js');
+        const res = await loginWithToken('abcd');
+        expect(res.ok).toBe(false);
+        if (!res.ok) expect(res.reason).toBe('unreachable');
+    });
+});
+
+describe('fetchStatus', () => {
+    it('normalizes camelCase / PascalCase entries', async () => {
+        (globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValueOnce(
+            new Response(
+                JSON.stringify([
+                    { id: 1, port: 3072, name: 'kino der toten', currentPlayers: 3 },
+                    { Id: 2, Port: 3073, Name: 'ascension', CurrentPlayers: 0 }
+                ]),
+                { status: 200, headers: { 'Content-Type': 'application/json' } }
+            )
+        );
+        const { fetchStatus } = await import('../../src/lib/server/integrations/iw4m.js');
+        const res = await fetchStatus();
+        expect(res.ok).toBe(true);
+        if (res.ok) {
+            expect(res.entries[0].currentPlayers).toBe(3);
+            expect(res.entries[1].name).toBe('ascension');
+        }
+    });
+});

tests/unit/push.test.ts

@@ -0,0 +1,63 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { newFixture, type Fixture } from '../helpers/fixture.js';
+
+let fixture: Fixture;
+
+beforeEach(async () => {
+    vi.resetModules();
+    fixture = await newFixture(
+        {
+            'hud.gsc': 'v1',
+            'zom.gsc': 'v1',
+            'perks/perk1.gsc': 'p1'
+        },
+        ['t5_kino_1', 't5_ascension_1']
+    );
+});
+
+afterEach(async () => {
+    await fixture.cleanup();
+});
+
+describe('doPush', () => {
+    it('adds every source file on a fresh server', async () => {
+        const { doPush } = await import('../../src/lib/server/fleet/push.js');
+        const { seedServerRegistry } = await import('../../src/lib/server/fleet/servers.js');
+        await seedServerRegistry();
+
+        const res = await doPush({ patterns: ['*'], dryRun: false, create: false });
+        expect(res.totalChangedServers).toBe(2);
+        expect(res.totalFiles).toBe(3 * 2);
+        expect(res.deploymentId).toBeTruthy();
+
+        const written = await readFile(join(fixture.t5, 't5_kino_1', 'runtime/plutonium/storage/t5/raw/scripts/sp/hud.gsc'), 'utf8');
+        expect(written).toBe('v1');
+    });
+
+    it('dry-run makes no changes and creates no deployment row', async () => {
+        const { doPush } = await import('../../src/lib/server/fleet/push.js');
+        const { seedServerRegistry } = await import('../../src/lib/server/fleet/servers.js');
+        await seedServerRegistry();
+
+        const res = await doPush({ patterns: ['*'], dryRun: true, create: false });
+        expect(res.deploymentId).toBeNull();
+        expect(res.totalChangedServers).toBe(2);
+
+        // no file created
+        await expect(readFile(join(fixture.t5, 't5_kino_1', 'runtime/plutonium/storage/t5/raw/scripts/sp/hud.gsc'))).rejects.toThrow();
+    });
+
+    it('skips servers that are already up to date', async () => {
+        const { doPush } = await import('../../src/lib/server/fleet/push.js');
+        const { seedServerRegistry } = await import('../../src/lib/server/fleet/servers.js');
+        await seedServerRegistry();
+        await doPush({ patterns: ['*'], dryRun: false });
+
+        // second run: everything matches → no deployment
+        const res = await doPush({ patterns: ['*'], dryRun: false });
+        expect(res.deploymentId).toBeNull();
+        expect(res.totalChangedServers).toBe(0);
+    });
+});

tests/unit/sweep.test.ts

@@ -0,0 +1,53 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { newFixture, type Fixture } from '../helpers/fixture.js';
+
+let fixture: Fixture;
+
+beforeEach(async () => {
+    vi.resetModules();
+    fixture = await newFixture({ 'hud.gsc': 'v1' }, ['t5_kino_1', 't5_ascension_1']);
+    // No integrations → sweep marks rows manual, exercising that branch.
+    delete process.env.KOMODO_ADDRESS;
+    delete process.env.IW4M_ADDRESS;
+});
+
+afterEach(async () => {
+    await fixture.cleanup();
+});
+
+describe('sweep', () => {
+    it('marks all pending rows manual when integrations are unset', async () => {
+        const { doPush } = await import('../../src/lib/server/fleet/push.js');
+        const { sweep } = await import('../../src/lib/server/pipeline/sweep.js');
+        const { seedServerRegistry } = await import('../../src/lib/server/fleet/servers.js');
+        const { setAuthState } = await import('../../src/lib/server/integrations/auth-state.js');
+        const { db } = await import('../../src/lib/server/db/index.js');
+        await seedServerRegistry();
+
+        // Force ready so pipelineReady() lets sweep run (even though
+        // integrations are off — that's the branch we want to test).
+        setAuthState({ kind: 'ready', token: 'abcd', cookie: 'x=y', expiresAt: Date.now() + 100_000 });
+
+        const push = await doPush({ patterns: ['*'] });
+        expect(push.deploymentId).not.toBeNull();
+
+        const result = await sweep();
+        expect(result.frozen).toBe(false);
+
+        const rows = db()
+            .prepare("SELECT restart_state FROM deployment_servers WHERE deployment_id = ?")
+            .all(push.deploymentId!) as Array<{ restart_state: string }>;
+        for (const r of rows) expect(r.restart_state).toBe('manual');
+    });
+
+    it('freezes when auth is not ready', async () => {
+        const { doPush } = await import('../../src/lib/server/fleet/push.js');
+        const { sweep } = await import('../../src/lib/server/pipeline/sweep.js');
+        const { seedServerRegistry } = await import('../../src/lib/server/fleet/servers.js');
+        await seedServerRegistry();
+
+        await doPush({ patterns: ['*'] });
+        const result = await sweep();
+        expect(result.frozen).toBe(true);
+    });
+});