feat(api): add tool filtering and DB-backed cleanup settings

Add feature flag support to skip disabled/experimental tools at startup
by reading disabledTools and enableExperimentalTools from the settings
table. Refactor cleanup.ts to read tempFileMaxAgeHours from DB settings
(with env var fallback) and respect the startupCleanup setting.

tests/integration/settings-phase1.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Integration tests for Phase 1 settings keys:
+ * disabledTools, enableExperimentalTools, tempFileMaxAgeHours, startupCleanup
+ *
+ * These verify the settings store correctly persists and retrieves these keys
+ * via the PUT/GET /api/v1/settings endpoints.
+ */
+
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { db, schema } from "../../apps/api/src/db/index.js";
+import { buildTestApp, loginAsAdmin, type TestApp } from "./test-server.js";
+
+let testApp: TestApp;
+let app: TestApp["app"];
+let adminToken: string;
+
+beforeAll(async () => {
+  testApp = await buildTestApp();
+  app = testApp.app;
+  adminToken = await loginAsAdmin(app);
+}, 30_000);
+
+afterAll(async () => {
+  await testApp.cleanup();
+}, 10_000);
+
+// ═══════════════════════════════════════════════════════════════════════════
+// disabledTools
+// ═══════════════════════════════════════════════════════════════════════════
+describe("disabledTools setting", () => {
+  it("can be saved as a JSON array and retrieved", async () => {
+    const disabledTools = ["resize", "crop", "rotate"];
+
+    // Save
+    const putRes = await app.inject({
+      method: "PUT",
+      url: "/api/v1/settings",
+      headers: { authorization: `Bearer ${adminToken}` },
+      payload: { disabledTools },
+    });
+    expect(putRes.statusCode).toBe(200);
+    expect(JSON.parse(putRes.body).ok).toBe(true);
+
+    // Retrieve via GET all
+    const getRes = await app.inject({
+      method: "GET",
+      url: "/api/v1/settings",
+      headers: { authorization: `Bearer ${adminToken}` },
+    });
+    expect(getRes.statusCode).toBe(200);
+    const body = JSON.parse(getRes.body);
+    const parsed = JSON.parse(body.settings.disabledTools);
+    expect(parsed).toEqual(disabledTools);
+
+    // Retrieve via GET specific key
+    const keyRes = await app.inject({
+      method: "GET",
+      url: "/api/v1/settings/disabledTools",
+      headers: { authorization: `Bearer ${adminToken}` },
+    });
+    expect(keyRes.statusCode).toBe(200);
+    const keyBody = JSON.parse(keyRes.body);
+    expect(JSON.parse(keyBody.value)).toEqual(disabledTools);
+  });
+
+  it("can be updated to an empty array", async () => {
+    const putRes = await app.inject({
+      method: "PUT",
+      url: "/api/v1/settings",
+      headers: { authorization: `Bearer ${adminToken}` },
+      payload: { disabledTools: [] },
+    });
+    expect(putRes.statusCode).toBe(200);
+
+    const keyRes = await app.inject({
+      method: "GET",
+      url: "/api/v1/settings/disabledTools",
+      headers: { authorization: `Bearer ${adminToken}` },
+    });
+    expect(keyRes.statusCode).toBe(200);
+    expect(JSON.parse(JSON.parse(keyRes.body).value)).toEqual([]);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// enableExperimentalTools
+// ═══════════════════════════════════════════════════════════════════════════
+describe("enableExperimentalTools setting", () => {
+  it("can be saved and retrieved as 'true'", async () => {
+    const putRes = await app.inject({
+      method: "PUT",
+      url: "/api/v1/settings",
+      headers: { authorization: `Bearer ${adminToken}` },
+      payload: { enableExperimentalTools: "true" },
+    });
+    expect(putRes.statusCode).toBe(200);
+
+    const keyRes = await app.inject({
+      method: "GET",
+      url: "/api/v1/settings/enableExperimentalTools",
+      headers: { authorization: `Bearer ${adminToken}` },
+    });
+    expect(keyRes.statusCode).toBe(200);
+    expect(JSON.parse(keyRes.body).value).toBe("true");
+  });
+
+  it("can be saved and retrieved as 'false'", async () => {
+    const putRes = await app.inject({
+      method: "PUT",
+      url: "/api/v1/settings",
+      headers: { authorization: `Bearer ${adminToken}` },
+      payload: { enableExperimentalTools: "false" },
+    });
+    expect(putRes.statusCode).toBe(200);
+
+    const keyRes = await app.inject({
+      method: "GET",
+      url: "/api/v1/settings/enableExperimentalTools",
+      headers: { authorization: `Bearer ${adminToken}` },
+    });
+    expect(keyRes.statusCode).toBe(200);
+    expect(JSON.parse(keyRes.body).value).toBe("false");
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// tempFileMaxAgeHours
+// ═══════════════════════════════════════════════════════════════════════════
+describe("tempFileMaxAgeHours setting", () => {
+  it("can be saved and retrieved as a numeric string", async () => {
+    const putRes = await app.inject({
+      method: "PUT",
+      url: "/api/v1/settings",
+      headers: { authorization: `Bearer ${adminToken}` },
+      payload: { tempFileMaxAgeHours: "48" },
+    });
+    expect(putRes.statusCode).toBe(200);
+
+    const keyRes = await app.inject({
+      method: "GET",
+      url: "/api/v1/settings/tempFileMaxAgeHours",
+      headers: { authorization: `Bearer ${adminToken}` },
+    });
+    expect(keyRes.statusCode).toBe(200);
+    expect(JSON.parse(keyRes.body).value).toBe("48");
+  });
+
+  it("can be updated to a different value", async () => {
+    // Set initial value
+    await app.inject({
+      method: "PUT",
+      url: "/api/v1/settings",
+      headers: { authorization: `Bearer ${adminToken}` },
+      payload: { tempFileMaxAgeHours: "12" },
+    });
+
+    // Update
+    const putRes = await app.inject({
+      method: "PUT",
+      url: "/api/v1/settings",
+      headers: { authorization: `Bearer ${adminToken}` },
+      payload: { tempFileMaxAgeHours: "72" },
+    });
+    expect(putRes.statusCode).toBe(200);
+
+    const keyRes = await app.inject({
+      method: "GET",
+      url: "/api/v1/settings/tempFileMaxAgeHours",
+      headers: { authorization: `Bearer ${adminToken}` },
+    });
+    expect(JSON.parse(keyRes.body).value).toBe("72");
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// startupCleanup
+// ═══════════════════════════════════════════════════════════════════════════
+describe("startupCleanup setting", () => {
+  it("can be saved and retrieved as 'true'", async () => {
+    const putRes = await app.inject({
+      method: "PUT",
+      url: "/api/v1/settings",
+      headers: { authorization: `Bearer ${adminToken}` },
+      payload: { startupCleanup: "true" },
+    });
+    expect(putRes.statusCode).toBe(200);
+
+    const keyRes = await app.inject({
+      method: "GET",
+      url: "/api/v1/settings/startupCleanup",
+      headers: { authorization: `Bearer ${adminToken}` },
+    });
+    expect(keyRes.statusCode).toBe(200);
+    expect(JSON.parse(keyRes.body).value).toBe("true");
+  });
+
+  it("can be saved and retrieved as 'false'", async () => {
+    const putRes = await app.inject({
+      method: "PUT",
+      url: "/api/v1/settings",
+      headers: { authorization: `Bearer ${adminToken}` },
+      payload: { startupCleanup: "false" },
+    });
+    expect(putRes.statusCode).toBe(200);
+
+    const keyRes = await app.inject({
+      method: "GET",
+      url: "/api/v1/settings/startupCleanup",
+      headers: { authorization: `Bearer ${adminToken}` },
+    });
+    expect(keyRes.statusCode).toBe(200);
+    expect(JSON.parse(keyRes.body).value).toBe("false");
+  });
+});

tests/unit/api/cleanup.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Tests for cleanup.ts helper functions:
+ * getMaxAgeMs and shouldRunStartupCleanup.
+ *
+ * These test the DB-backed settings lookup with fallback to env vars.
+ * Requires migrations to be run first (shared DB from vitest env).
+ */
+
+import { eq } from "drizzle-orm";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+import { db, schema } from "../../../apps/api/src/db/index.js";
+import { runMigrations } from "../../../apps/api/src/db/migrate.js";
+import { getMaxAgeMs, shouldRunStartupCleanup } from "../../../apps/api/src/lib/cleanup.js";
+
+// Run migrations once to ensure the settings table exists
+beforeAll(() => {
+  runMigrations();
+});
+
+// Helper to insert a setting
+function setSetting(key: string, value: string) {
+  const existing = db.select().from(schema.settings).where(eq(schema.settings.key, key)).get();
+  if (existing) {
+    db.update(schema.settings)
+      .set({ value, updatedAt: new Date() })
+      .where(eq(schema.settings.key, key))
+      .run();
+  } else {
+    db.insert(schema.settings).values({ key, value }).run();
+  }
+}
+
+// Helper to remove a setting
+function removeSetting(key: string) {
+  db.delete(schema.settings).where(eq(schema.settings.key, key)).run();
+}
+
+afterEach(() => {
+  removeSetting("tempFileMaxAgeHours");
+  removeSetting("startupCleanup");
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// getMaxAgeMs
+// ═══════════════════════════════════════════════════════════════════════════
+describe("getMaxAgeMs", () => {
+  it("returns DB value when tempFileMaxAgeHours is set", () => {
+    setSetting("tempFileMaxAgeHours", "48");
+    const result = getMaxAgeMs();
+    expect(result).toBe(48 * 60 * 60 * 1000);
+  });
+
+  it("returns env fallback when no DB setting exists", () => {
+    removeSetting("tempFileMaxAgeHours");
+    const result = getMaxAgeMs();
+    // vitest.config.ts sets FILE_MAX_AGE_HOURS=1
+    expect(result).toBe(1 * 60 * 60 * 1000);
+  });
+
+  it("returns env fallback for invalid (non-numeric) DB value", () => {
+    setSetting("tempFileMaxAgeHours", "notanumber");
+    const result = getMaxAgeMs();
+    expect(result).toBe(1 * 60 * 60 * 1000);
+  });
+
+  it("returns env fallback for zero or negative DB value", () => {
+    setSetting("tempFileMaxAgeHours", "0");
+    const result = getMaxAgeMs();
+    expect(result).toBe(1 * 60 * 60 * 1000);
+
+    setSetting("tempFileMaxAgeHours", "-5");
+    const result2 = getMaxAgeMs();
+    expect(result2).toBe(1 * 60 * 60 * 1000);
+  });
+
+  it("handles fractional hours", () => {
+    setSetting("tempFileMaxAgeHours", "0.5");
+    const result = getMaxAgeMs();
+    expect(result).toBe(0.5 * 60 * 60 * 1000);
+  });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// shouldRunStartupCleanup
+// ═══════════════════════════════════════════════════════════════════════════
+describe("shouldRunStartupCleanup", () => {
+  it("returns false when setting is 'false'", () => {
+    setSetting("startupCleanup", "false");
+    expect(shouldRunStartupCleanup()).toBe(false);
+  });
+
+  it("returns true when setting is 'true'", () => {
+    setSetting("startupCleanup", "true");
+    expect(shouldRunStartupCleanup()).toBe(true);
+  });
+
+  it("returns true when setting is not set", () => {
+    removeSetting("startupCleanup");
+    expect(shouldRunStartupCleanup()).toBe(true);
+  });
+
+  it("returns true for any value other than 'false'", () => {
+    setSetting("startupCleanup", "yes");
+    expect(shouldRunStartupCleanup()).toBe(true);
+
+    setSetting("startupCleanup", "1");
+    expect(shouldRunStartupCleanup()).toBe(true);
+  });
+});