feat(server): add the schedule wiring

server/tests/integration/scheduler-gate.test.ts

@@ -0,0 +1,80 @@
+/**
+ * SCHED-GATE — the no-timers-in-the-harness regression test. buildApp() is
+ * shared with every integration/e2e suite, and job providers register their
+ * crons from onApplicationBootstrap, which app.init() fires on every boot.
+ * This proves the CronRegistrarService NODE_ENV=test gate holds: a full
+ * harness boot registers zero cron jobs, intervals or timeouts, and closing
+ * the app leaves nothing behind. If this ever goes red, some job bypassed the
+ * registrar (or used a @Cron decorator) and every suite is now running real
+ * timers.
+ */
+import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
+import type { INestApplication } from '@nestjs/common';
+
+const { testDb, dbMock } = vi.hoisted(() => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const Database = require('better-sqlite3');
+  const db = new Database(':memory:');
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA foreign_keys = ON');
+  db.exec('PRAGMA busy_timeout = 5000');
+  const mock = {
+    db,
+    closeDb: () => {},
+    reinitialize: () => {},
+    getPlaceWithTags: () => null,
+    canAccessTrip: () => undefined,
+    isOwner: () => false,
+  };
+  return { testDb: db, dbMock: mock };
+});
+
+vi.mock('../../src/db/database', () => dbMock);
+vi.mock('../../src/config', () => ({
+  JWT_SECRET: 'test-jwt-secret-for-trek-testing-only',
+  ENCRYPTION_KEY: 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2a3b4c5d6a7b8c9d0e1f2',
+  updateJwtSecret: () => {},
+  SESSION_DURATION: '24h',
+  SESSION_DURATION_MS: 86400000,
+  SESSION_DURATION_SECONDS: 86400,
+  DEFAULT_LANGUAGE: 'en',
+}));
+vi.mock('../../src/websocket', () => ({ broadcast: vi.fn(), broadcastToUser: vi.fn() }));
+
+import { SchedulerRegistry } from '@nestjs/schedule';
+import { createTables } from '../../src/db/schema';
+import { runMigrations } from '../../src/db/migrations';
+import { CronRegistrarService } from '../../src/nest/scheduling/cron-registrar.service';
+import { buildApp } from '../../src/bootstrap';
+
+describe('SCHED-GATE — the harness boots without scheduling anything', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    createTables(testDb);
+    runMigrations(testDb);
+    app = await buildApp();
+  });
+
+  afterAll(() => {
+    testDb.close();
+  });
+
+  it('SCHED-GATE-001 — the registrar reports the test gate closed', () => {
+    expect(app.get(CronRegistrarService).isEnabled()).toBe(false);
+  });
+
+  it('SCHED-GATE-002 — a full app boot registers zero cron jobs, intervals and timeouts', () => {
+    const registry = app.get(SchedulerRegistry);
+    expect(registry.getCronJobs().size).toBe(0);
+    expect(registry.getIntervals()).toHaveLength(0);
+    expect(registry.getTimeouts()).toHaveLength(0);
+    expect(app.get(CronRegistrarService).jobCount).toBe(0);
+  });
+
+  it('SCHED-GATE-003 — app.close() leaves the registrar empty (shutdown parity)', async () => {
+    const registrar = app.get(CronRegistrarService);
+    await app.close();
+    expect(registrar.jobCount).toBe(0);
+  });
+});

server/tests/unit/nest/cron-registrar.service.test.ts

@@ -0,0 +1,143 @@
+/**
+ * CronRegistrarService — the shared cron gate every job provider schedules
+ * through. Proves the NODE_ENV=test gate refuses to schedule, the timezone is
+ * resolved at register() time ('app' vs 'none'), re-registering a name replaces
+ * the old job, unregister is idempotent, and onApplicationShutdown stops
+ * everything the registrar owns.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const h = vi.hoisted(() => ({
+  jobs: [] as Array<{
+    cronTime: string;
+    timeZone?: string;
+    start?: boolean;
+    onTick: () => unknown;
+    stopped: boolean;
+    stop(): void;
+  }>,
+}));
+vi.mock('cron', () => ({
+  CronJob: {
+    from: (opts: { cronTime: string; timeZone?: string; start?: boolean; onTick: () => unknown }) => {
+      const job = {
+        ...opts,
+        stopped: false,
+        stop() {
+          this.stopped = true;
+        },
+      };
+      h.jobs.push(job);
+      return job;
+    },
+  },
+}));
+
+import { SchedulerRegistry } from '@nestjs/schedule';
+import { CronRegistrarService } from '../../../src/nest/scheduling/cron-registrar.service';
+import type { RuntimeEnvService } from '../../../src/nest/app-config/runtime-env.service';
+
+function makeRegistrar(isTest: boolean) {
+  const registry = new SchedulerRegistry();
+  const runtimeEnv = { isTest: () => isTest } as RuntimeEnvService;
+  return { registrar: new CronRegistrarService(registry, runtimeEnv), registry };
+}
+
+describe('CronRegistrarService', () => {
+  const originalTz = process.env.TZ;
+
+  beforeEach(() => {
+    h.jobs.length = 0;
+    delete process.env.TZ;
+  });
+
+  afterEach(() => {
+    if (originalTz === undefined) delete process.env.TZ;
+    else process.env.TZ = originalTz;
+  });
+
+  it('CRONREG-001 — refuses to schedule under the test gate (register returns false, nothing created)', () => {
+    const { registrar, registry } = makeRegistrar(true);
+    expect(registrar.isEnabled()).toBe(false);
+    expect(registrar.register('job', '0 * * * *', () => {})).toBe(false);
+    expect(h.jobs).toHaveLength(0);
+    expect(registry.getCronJobs().size).toBe(0);
+    expect(registrar.jobCount).toBe(0);
+  });
+
+  it('CRONREG-002 — schedules a started job with tz UTC when TZ is unset', () => {
+    const { registrar, registry } = makeRegistrar(false);
+    expect(registrar.register('job', '0 3 * * *', () => {})).toBe(true);
+    expect(h.jobs).toHaveLength(1);
+    expect(h.jobs[0].cronTime).toBe('0 3 * * *');
+    expect(h.jobs[0].start).toBe(true);
+    expect(h.jobs[0].timeZone).toBe('UTC');
+    expect(registry.getCronJobs().size).toBe(1);
+    expect(registrar.jobCount).toBe(1);
+  });
+
+  it('CRONREG-003 — resolves the app timezone from the env at register() time', () => {
+    const { registrar } = makeRegistrar(false);
+    process.env.TZ = 'Europe/Zurich';
+    registrar.register('job', '0 9 * * *', () => {});
+    expect(h.jobs[0].timeZone).toBe('Europe/Zurich');
+
+    // A re-register picks up a changed TZ — the read is per call, never cached.
+    process.env.TZ = 'America/New_York';
+    registrar.register('job', '0 9 * * *', () => {});
+    expect(h.jobs[1].timeZone).toBe('America/New_York');
+  });
+
+  it("CRONREG-004 — timezone: 'none' schedules in the server-local zone even when TZ is set", () => {
+    const { registrar } = makeRegistrar(false);
+    process.env.TZ = 'Europe/Zurich';
+    registrar.register('job', '0 * * * *', () => {}, { timezone: 'none' });
+    expect(h.jobs[0].timeZone).toBeUndefined();
+  });
+
+  it('CRONREG-005 — re-registering a name stops the old job and replaces it', () => {
+    const { registrar, registry } = makeRegistrar(false);
+    registrar.register('job', '0 2 * * *', () => {});
+    registrar.register('job', '0 4 * * *', () => {});
+    expect(h.jobs[0].stopped).toBe(true);
+    expect(h.jobs[1].stopped).toBe(false);
+    expect(registry.getCronJobs().size).toBe(1);
+    expect(registrar.jobCount).toBe(1);
+    expect(registry.getCronJob('job').cronTime).toBe('0 4 * * *');
+  });
+
+  it('CRONREG-006 — unregister stops and drops the job, and is a no-op for unknown names', () => {
+    const { registrar, registry } = makeRegistrar(false);
+    registrar.register('job', '0 2 * * *', () => {});
+    registrar.unregister('job');
+    expect(h.jobs[0].stopped).toBe(true);
+    expect(registry.getCronJobs().size).toBe(0);
+    expect(registrar.jobCount).toBe(0);
+    expect(() => registrar.unregister('job')).not.toThrow();
+    expect(() => registrar.unregister('never-existed')).not.toThrow();
+  });
+
+  it('CRONREG-007 — onApplicationShutdown stops every job the registrar owns', () => {
+    const { registrar, registry } = makeRegistrar(false);
+    registrar.register('a', '0 2 * * *', () => {});
+    registrar.register('b', '0 4 * * *', () => {});
+    registrar.onApplicationShutdown();
+    expect(h.jobs.every(j => j.stopped)).toBe(true);
+    expect(registry.getCronJobs().size).toBe(0);
+    expect(registrar.jobCount).toBe(0);
+  });
+
+  it('CRONREG-008 — the disabled path still clears an already-registered name (restart parity)', () => {
+    // A dynamic job (auto-backup) restarts by re-registering; if settings turn
+    // it off the register call must still drop the old schedule.
+    const registry = new SchedulerRegistry();
+    let testMode = false;
+    const registrar = new CronRegistrarService(registry, { isTest: () => testMode } as RuntimeEnvService);
+    registrar.register('job', '0 2 * * *', () => {});
+    testMode = true;
+    expect(registrar.register('job', '0 4 * * *', () => {})).toBe(false);
+    expect(h.jobs[0].stopped).toBe(true);
+    expect(registry.getCronJobs().size).toBe(0);
+    expect(registrar.jobCount).toBe(0);
+  });
+});