feat(utils): define file config (medusajs#13283)

** What
 - Allow auto-loaded Medusa files to export a config object.
 - Currently supports isDisabled to control loading.
 - new instance `FeatureFlag` exported by `@medusajs/framework/utils`
 - `feature-flags` is now a supported folder for medusa projects, modules, providers and plugins. They will be loaded and added to `FeatureFlag`

** Why
 - Enables conditional loading of routes, migrations, jobs, subscribers, workflows, and other files based on feature flags.

```ts
// /src/feature-flags

import { FlagSettings } from "@medusajs/framework/feature-flags"

const CustomFeatureFlag: FlagSettings = {
  key: "custom_feature",
  default_val: false,
  env_key: "FF_MY_CUSTOM_FEATURE",
  description: "Enable xyz",
}

export default CustomFeatureFlag
```

```ts
// /src/modules/my-custom-module/migration/Migration20250822135845.ts

import { FeatureFlag } from "@medusajs/framework/utils"

export class Migration20250822135845 extends Migration {
  override async up(){ }
  override async down(){ }
}

defineFileConfig({
  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_feature")
})
```

Author: carlos-r-l-rodrigues

.changeset/dry-geckos-act.md

@@ -0,0 +1,12 @@
+---
+"@medusajs/modules-sdk": patch
+"@medusajs/framework": patch
+"@medusajs/types": patch
+"@medusajs/utils": patch
+"@medusajs/medusa": patch
+"@medusajs/test-utils": patch
+"@medusajs/workflows-sdk": patch
+"@medusajs/cli": patch
+---
+
+feat: define file config and improved feature flag support

integration-tests/http/__fixtures__/feature-flag/medusa-config.ts

@@ -0,0 +1,26 @@
+const { defineConfig } = require("@medusajs/framework/utils")
+
+const DB_HOST = process.env.DB_HOST
+const DB_USERNAME = process.env.DB_USERNAME
+const DB_PASSWORD = process.env.DB_PASSWORD
+const DB_NAME = process.env.DB_TEMP_NAME
+const DB_URL = `postgres://${DB_USERNAME}:${DB_PASSWORD}@${DB_HOST}/${DB_NAME}`
+
+process.env.DATABASE_URL = DB_URL
+
+module.exports = defineConfig({
+  admin: {
+    disable: true,
+  },
+  projectConfig: {
+    http: {
+      jwtSecret: "secret",
+    },
+  },
+  modules: [
+    {
+      key: "custom",
+      resolve: "src/modules/custom",
+    },
+  ],
+})

integration-tests/http/__fixtures__/feature-flag/src/api/custom/route.ts

@@ -0,0 +1,10 @@
+import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { defineFileConfig, FeatureFlag } from "@medusajs/utils"
+
+defineFileConfig({
+  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_ff"),
+})
+
+export const GET = async (req: MedusaRequest, res: MedusaResponse) => {
+  res.json({ message: "Custom GET" })
+}

integration-tests/http/__fixtures__/feature-flag/src/feature-flags/custom-ff.ts

@@ -0,0 +1,8 @@
+import { FlagSettings } from "@medusajs/framework/feature-flags"
+
+export const CustomFeatureFlag: FlagSettings = {
+  key: "custom_ff",
+  default_val: false,
+  env_key: "CUSTOM_FF",
+  description: "Custom feature flag",
+}

integration-tests/http/__fixtures__/feature-flag/src/jobs/test-job.ts

@@ -0,0 +1,18 @@
+import { MedusaContainer } from "@medusajs/framework/types"
+import { defineFileConfig, FeatureFlag } from "@medusajs/framework/utils"
+
+export const testJobHandler = jest.fn()
+
+export default async function greetingJob(container: MedusaContainer) {
+  testJobHandler()
+}
+
+export const config = {
+  name: "greeting-every-second",
+  numberOfExecutions: 1,
+  schedule: "* * * * * *",
+}
+
+defineFileConfig({
+  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_ff"),
+})

integration-tests/http/__fixtures__/feature-flag/src/modules/custom/index.ts

@@ -0,0 +1,8 @@
+import { ModuleExports } from "@medusajs/types"
+import { ModuleService } from "./services/module-service"
+
+const moduleExports: ModuleExports = {
+  service: ModuleService,
+}
+
+export default moduleExports

integration-tests/http/__fixtures__/feature-flag/src/modules/custom/migrations/MigrationTest.ts

@@ -0,0 +1,12 @@
+import { FeatureFlag, defineFileConfig } from "@medusajs/framework/utils"
+import { Migration } from "@mikro-orm/migrations"
+
+defineFileConfig({
+  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_ff"),
+})
+
+export class MigrationTest extends Migration {
+  override async up(): Promise<void> {}
+
+  override async down(): Promise<void> {}
+}

integration-tests/http/__fixtures__/feature-flag/src/modules/custom/services/module-service.ts

@@ -0,0 +1,12 @@
+import { IModuleService } from "@medusajs/types"
+import { MedusaContext } from "@medusajs/utils"
+
+// @ts-expect-error
+export class ModuleService implements IModuleService {
+  public property = "value"
+
+  constructor() {}
+  async methodName(input, @MedusaContext() context) {
+    return input + " called"
+  }
+}

integration-tests/http/__fixtures__/feature-flag/src/subscribers/test-event-payload.ts

@@ -0,0 +1,13 @@
+import { defineFileConfig, FeatureFlag } from "@medusajs/framework/utils"
+
+const testProductCreatedHandlerMock = jest.fn()
+
+export default testProductCreatedHandlerMock
+
+export const config = {
+  event: "event.test",
+}
+
+defineFileConfig({
+  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_ff"),
+})

integration-tests/http/__fixtures__/feature-flag/src/workflows/test-workflow.ts

@@ -0,0 +1,14 @@
+import { defineFileConfig, FeatureFlag } from "@medusajs/framework/utils"
+import { createStep, createWorkflow } from "@medusajs/framework/workflows-sdk"
+
+const testWorkflowHandler = jest.fn()
+
+const step1 = createStep("step1", () => testWorkflowHandler())
+
+export const testWorkflow = createWorkflow("test-workflow", () => {
+  step1()
+})
+
+defineFileConfig({
+  isDisabled: () => !FeatureFlag.isFeatureEnabled("custom_ff"),
+})