fix(express): content-negotiated 404 for unmatched routes (#3975)

The catch-all route previously sent the friendly "Devkit Node Api" HTML
snippet with an implicit 200 for every unmatched path, including /api/*
typos. API consumers and automated agents relying on status codes for
error handling saw false-positive success responses.

Register the root route explicitly (keeps the friendly HTML at 200,
only reached when static hosting served no index.html) before the
catch-all, since Express 5's `/{*path}` also matches `/`. The catch-all
now returns 404 with JSON `{ error: 'not_found' }` for /api/* paths or
when the request explicitly accepts application/json, and a minimal
HTML 404 otherwise. Non-GET methods are unaffected (already 404 by
default).

Adds unit tests covering: unknown /api path -> JSON 404, /api without
trailing slash -> JSON 404, unknown page with Accept: text/html -> HTML
404, unknown page with Accept: application/json -> JSON 404, and root
route unchanged at 200.

Author: PierreBrisorgueil

lib/services/express.js

@@ -279,9 +279,22 @@ const initModulesServerRoutes = async (app) => {
     const route = await import(path.resolve(routePath));
     route.default(app);
   }
-  app.get('/{*path}', (req, res) => {
+  // Explicit root route: keeps the friendly landing page at 200, only reached
+  // when express.static served no public/index.html. Must be registered
+  // before the catch-all below, since Express 5's `/{*path}` also matches `/`.
+  app.get('/', (req, res) => {
     res.send('<center><br /><h1>Devkit Node Api</h1><h3>Available on <a href="/api/tasks">/api</a>. #LetsGetTogether</h3></center>');
   });
+  // Catch-all for every other unmatched path: content-negotiated 404 instead
+  // of the previous implicit 200 HTML (#3975). API consumers and automated
+  // agents get a proper JSON error instead of a false-positive success.
+  app.get('/{*path}', (req, res) => {
+    const isApiPath = /^\/api(\/|$)/.test(req.path);
+    if (isApiPath || req.accepts(['html', 'json']) === 'json') {
+      return res.status(404).json({ error: 'not_found' });
+    }
+    res.status(404).send('<center><br /><h1>404</h1><h3>Not Found</h3></center>');
+  });
 };
 
 /**

lib/services/tests/express.notfound.unit.tests.js

@@ -0,0 +1,122 @@
+/**
+ * Module dependencies.
+ *
+ * Unit tests for express.js initModulesServerRoutes — content-negotiated 404
+ * for unmatched routes (#3975). Unknown routes must no longer return an
+ * implicit 200 HTML page; API paths and explicit JSON accepts must get a
+ * JSON 404, everything else a minimal HTML 404, and root behavior must be
+ * unchanged.
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import express from 'express';
+import request from 'supertest';
+
+describe('express initModulesServerRoutes — content-negotiated 404 (#3975):', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  /**
+   * Helper: extract initModulesServerRoutes from express.js (with all heavy
+   * deps mocked) and mount it on a fresh Express app.
+   * @returns {Promise<import('express').Express>} A ready-to-request Express app
+   */
+  const getApp = async () => {
+    jest.unstable_mockModule('../../../config/index.js', () => ({
+      default: {
+        domain: 'http://localhost:3000',
+        app: { title: 'Test', description: '', keywords: '', url: '', logo: '' },
+        secure: { ssl: false },
+        log: {},
+        bodyParser: {},
+        csrf: {},
+        cors: { origin: [], credentials: false, optionsSuccessStatus: 200 },
+        trust: { proxy: false },
+        openapi: { enable: false },
+        files: { routes: [], configs: [], policies: [], preRoutes: [], openapi: [], guides: [] },
+        analytics: { posthog: { autoCapture: false } },
+        docs: {},
+      },
+    }));
+    jest.unstable_mockModule('../../../lib/services/logger.js', () => ({
+      default: {
+        warn: jest.fn(),
+        error: jest.fn(),
+        info: jest.fn(),
+        debug: jest.fn(),
+        getLogFormat: jest.fn().mockReturnValue('combined'),
+        getMorganOptions: jest.fn().mockReturnValue({}),
+      },
+    }));
+    jest.unstable_mockModule('../../../lib/helpers/guides.js', () => ({
+      default: { loadGuides: jest.fn().mockReturnValue([]), mergeGuidesIntoSpec: jest.fn() },
+    }));
+    jest.unstable_mockModule('../../../lib/middlewares/requestId.js', () => ({
+      default: jest.fn((req, res, next) => next()),
+    }));
+    jest.unstable_mockModule('../../../lib/middlewares/posthog-context.middleware.js', () => ({
+      posthogContextMiddleware: jest.fn((req, res, next) => next()),
+    }));
+    jest.unstable_mockModule('../../../lib/services/errorTracker.js', () => ({
+      default: { setupExpressErrorHandler: jest.fn() },
+    }));
+    jest.unstable_mockModule('../../../lib/services/analytics.js', () => ({
+      default: { init: jest.fn().mockResolvedValue(undefined), identify: jest.fn(), groupIdentify: jest.fn() },
+    }));
+    jest.unstable_mockModule('../../../lib/middlewares/analytics.js', () => ({
+      default: jest.fn((req, res, next) => next()),
+    }));
+    jest.unstable_mockModule('../../../lib/middlewares/policy.js', () => ({
+      default: { discoverPolicies: jest.fn().mockResolvedValue(undefined), defineAbilityFor: jest.fn().mockResolvedValue({}) },
+    }));
+
+    const mod = await import('../../../lib/services/express.js');
+    const app = express();
+    await mod.default.initModulesServerRoutes(app);
+    return app;
+  };
+
+  test('GET /api/nope → 404 JSON { error: "not_found" }', async () => {
+    const app = await getApp();
+
+    const res = await request(app).get('/api/nope').expect(404);
+
+    expect(res.headers['content-type']).toMatch(/json/);
+    expect(res.body).toEqual({ error: 'not_found' });
+  });
+
+  test('GET /api (no trailing slash) → 404 JSON', async () => {
+    const app = await getApp();
+
+    const res = await request(app).get('/api').expect(404);
+
+    expect(res.headers['content-type']).toMatch(/json/);
+    expect(res.body).toEqual({ error: 'not_found' });
+  });
+
+  test('GET /nope with Accept: text/html → 404 HTML, no JSON', async () => {
+    const app = await getApp();
+
+    const res = await request(app).get('/nope').set('Accept', 'text/html').expect(404);
+
+    expect(res.headers['content-type']).toMatch(/html/);
+    expect(res.text).toContain('404');
+  });
+
+  test('GET /nope with Accept: application/json → 404 JSON { error: "not_found" }', async () => {
+    const app = await getApp();
+
+    const res = await request(app).get('/nope').set('Accept', 'application/json').expect(404);
+
+    expect(res.headers['content-type']).toMatch(/json/);
+    expect(res.body).toEqual({ error: 'not_found' });
+  });
+
+  test('GET / → 200, friendly root page unchanged', async () => {
+    const app = await getApp();
+
+    const res = await request(app).get('/').expect(200);
+
+    expect(res.text).toContain('Devkit Node Api');
+  });
+});