feat(config): per-module activated flag (#3384)

* feat(config): add per-module `activated` flag to exclude deactivated modules (#3383)

Add `filterByActivation` to config helper that filters out routes, models,
policies, and swagger YAML for modules with `activated: false`. Core modules
(core, auth, users, home) are never filtered. Missing flag defaults to active.

* fix(config): normalize path separators in extractModuleName for Windows compat

* docs: add module activation migration entry

Author: PierreBrisorgueil

MIGRATIONS.md

@@ -4,6 +4,30 @@ Breaking changes and upgrade notes for downstream projects.
 
 ---
 
+## Module Activation Config (2026-04-05)
+
+Per-module `activated: true/false` config flag. When `activated: false`, the module's routes, policies, models, and swagger YAML are excluded from the app entirely.
+
+### What changed
+
+- New `filterByActivation(files, config)` in `lib/helpers/config.js` — filters all globbed file arrays by module activation status
+- `config/index.js` applies filtering after config merge to: routes, policies, models, swagger YAML, preRoutes, configs
+- Core modules (`core`, `auth`, `users`, `home`) are always active regardless of flag
+- New module config files with `activated: true` default: `audit`, `billing`, `organizations`, `uploads`, `tasks`
+
+### Action for downstream
+
+1. Run `/update-stack` to pull the change
+2. No breaking change — all modules default to `activated: true` (backward compatible)
+3. To deactivate a module, set `DEVKIT_NODE_{moduleName}_activated=false` in env vars or override in config:
+   ```js
+   // config/defaults/development.config.js
+   tasks: { activated: false }
+   ```
+4. If you have custom modules, add `activated: true` in their config file to be explicit
+
+---
+
 ## Decentralized Policy Subject Resolution (2026-04-03)
 
 Subject resolution in `lib/middlewares/policy.js` is now registry-based instead of hardcoded. Each module's policy file exports a `*SubjectRegistration()` function that registers its own document-level and path-level subjects during `discoverPolicies()`.

config/index.js

@@ -131,6 +131,13 @@ const initGlobalConfig = async () => {
   config = deepMerge(config, { package: packageJSON });
   // Initialize global globbed files
   config = deepMerge(config, { files: await configHelper.initGlobalConfigFiles(assets) });
+  // Filter files by module activation (deactivated modules are excluded)
+  const fileKeys = ['swagger', 'mongooseModels', 'sequelizeModels', 'preRoutes', 'routes', 'configs', 'policies'];
+  for (const key of fileKeys) {
+    if (config.files[key]) {
+      config.files[key] = configHelper.filterByActivation(config.files[key], config);
+    }
+  }
   // Init Secure SSL if can be used
   configHelper.initSecureMode(config);
   // Print a warning if config.domain is not set

lib/helpers/config.js

@@ -98,6 +98,42 @@ const initSecureMode = (config) => {
   }
 };
 
+/**
+ * Core modules that are always active regardless of the `activated` flag.
+ */
+const CORE_MODULES = new Set(['core', 'auth', 'users', 'home']);
+
+/**
+ * Extract the module name from a file path.
+ * E.g. `modules/tasks/routes/tasks.routes.js` → `tasks`
+ * @param {string} filePath
+ * @returns {string|null} module name or null if not inside modules/
+ */
+const extractModuleName = (filePath) => {
+  const normalizedPath = String(filePath).replace(/\\/g, '/');
+  const match = normalizedPath.match(/modules\/([^/]+)\//);
+  return match ? match[1] : null;
+};
+
+/**
+ * Filter file paths by module activation config.
+ * Files belonging to deactivated modules are excluded.
+ * Core modules are never filtered out.
+ * Missing `activated` key defaults to active (true).
+ *
+ * @param {string[]} files - array of file paths
+ * @param {object} config - merged configuration object
+ * @returns {string[]} filtered file paths
+ */
+const filterByActivation = (files, config) => files.filter((file) => {
+  const moduleName = extractModuleName(file);
+  if (!moduleName) return true; // not a module file, keep it
+  if (CORE_MODULES.has(moduleName)) return true; // core modules always active
+  const moduleConfig = config[moduleName];
+  if (!moduleConfig || moduleConfig.activated === undefined) return true; // default to active
+  return moduleConfig.activated !== false;
+});
+
 /**
  * Initialize global configuration files
  */
@@ -120,4 +156,6 @@ export default {
   validateJwtSecret,
   initSecureMode,
   initGlobalConfigFiles,
+  filterByActivation,
+  CORE_MODULES,
 };

lib/helpers/tests/config.filterByActivation.unit.tests.js

@@ -0,0 +1,114 @@
+/**
+ * Unit tests for filterByActivation in config helper.
+ */
+import configHelper from '../config.js';
+
+const { filterByActivation, CORE_MODULES } = configHelper;
+
+describe('filterByActivation', () => {
+  const files = [
+    'modules/core/routes/core.routes.js',
+    'modules/auth/routes/auth.routes.js',
+    'modules/users/routes/users.routes.js',
+    'modules/home/routes/home.routes.js',
+    'modules/tasks/routes/tasks.routes.js',
+    'modules/billing/routes/billing.routes.js',
+    'modules/audit/models/audit.mongoose.js',
+    'modules/organizations/policies/organizations.policy.js',
+    'modules/uploads/routes/uploads.routes.js',
+  ];
+
+  it('should keep all files when all modules are activated (default)', () => {
+    const config = {
+      tasks: { activated: true },
+      billing: { activated: true },
+      audit: { activated: true },
+      organizations: { activated: true },
+      uploads: { activated: true },
+    };
+    const result = filterByActivation(files, config);
+    expect(result).toEqual(files);
+  });
+
+  it('should filter out files from a deactivated non-core module', () => {
+    const config = {
+      tasks: { activated: false },
+      billing: { activated: true },
+    };
+    const result = filterByActivation(files, config);
+    expect(result).not.toContain('modules/tasks/routes/tasks.routes.js');
+    expect(result).toContain('modules/billing/routes/billing.routes.js');
+  });
+
+  it('should filter out multiple deactivated modules', () => {
+    const config = {
+      tasks: { activated: false },
+      billing: { activated: false },
+      audit: { activated: false },
+    };
+    const result = filterByActivation(files, config);
+    expect(result).not.toContain('modules/tasks/routes/tasks.routes.js');
+    expect(result).not.toContain('modules/billing/routes/billing.routes.js');
+    expect(result).not.toContain('modules/audit/models/audit.mongoose.js');
+    // Core modules still present
+    expect(result).toContain('modules/core/routes/core.routes.js');
+    expect(result).toContain('modules/auth/routes/auth.routes.js');
+    expect(result).toContain('modules/users/routes/users.routes.js');
+    expect(result).toContain('modules/home/routes/home.routes.js');
+  });
+
+  it('should never filter out core modules even if activated is false', () => {
+    const config = {
+      core: { activated: false },
+      auth: { activated: false },
+      users: { activated: false },
+      home: { activated: false },
+    };
+    const result = filterByActivation(files, config);
+    expect(result).toContain('modules/core/routes/core.routes.js');
+    expect(result).toContain('modules/auth/routes/auth.routes.js');
+    expect(result).toContain('modules/users/routes/users.routes.js');
+    expect(result).toContain('modules/home/routes/home.routes.js');
+  });
+
+  it('should default to active when activated key is missing', () => {
+    const config = {
+      tasks: { someOtherSetting: true }, // no activated key
+    };
+    const result = filterByActivation(files, config);
+    expect(result).toContain('modules/tasks/routes/tasks.routes.js');
+  });
+
+  it('should default to active when module has no config at all', () => {
+    const config = {}; // no module configs
+    const result = filterByActivation(files, config);
+    expect(result).toEqual(files);
+  });
+
+  it('should keep non-module files (no modules/ in path)', () => {
+    const mixedFiles = [
+      'config/defaults/development.config.js',
+      'lib/helpers/config.js',
+      'modules/tasks/routes/tasks.routes.js',
+    ];
+    const config = { tasks: { activated: false } };
+    const result = filterByActivation(mixedFiles, config);
+    expect(result).toContain('config/defaults/development.config.js');
+    expect(result).toContain('lib/helpers/config.js');
+    expect(result).not.toContain('modules/tasks/routes/tasks.routes.js');
+  });
+
+  it('should handle empty file array', () => {
+    const result = filterByActivation([], {});
+    expect(result).toEqual([]);
+  });
+
+  it('should define core, auth, users, home as core modules', () => {
+    expect(CORE_MODULES.has('core')).toBe(true);
+    expect(CORE_MODULES.has('auth')).toBe(true);
+    expect(CORE_MODULES.has('users')).toBe(true);
+    expect(CORE_MODULES.has('home')).toBe(true);
+    expect(CORE_MODULES.has('tasks')).toBe(false);
+    expect(CORE_MODULES.has('billing')).toBe(false);
+  });
+});

modules/audit/config/audit.development.config.js

@@ -1,5 +1,6 @@
 const config = {
   audit: {
+    activated: true,
     enabled: true,
     ttlDays: 90,
     captureIp: true,

modules/billing/config/billing.development.config.js

@@ -1,5 +1,6 @@
 const config = {
   billing: {
+    activated: true,
     // Plans available for subscriptions — extend as needed
     plans: ['free', 'starter', 'pro', 'enterprise'],
     // Quotas — downstream projects override these per plan:

modules/organizations/config/organizations.development.config.js

@@ -1,5 +1,6 @@
 const config = {
   organizations: {
+    activated: true,
     enabled: true, // false → B2C mode, organizations invisible
     autoCreate: true, // automatically create/join orgs at signup
     domainMatching: true, // match users to existing orgs by email domain

modules/tasks/config/tasks.development.config.js

@@ -0,0 +1,7 @@
+const config = {
+  tasks: {
+    activated: true,
+  },
+};
+
+export default config;

modules/uploads/config/uploads.development.config.js

@@ -1,5 +1,6 @@
 const config = {
   uploads: {
+    activated: true,
     sharp: {
       // default sharp settings for all uploads
       blur: 8,