feat(utils): define file config (#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")
})
```

packages/core/utils/src/feature-flags/analytics.ts

@@ -1,9 +0,0 @@
-import { FeatureFlagTypes } from "@medusajs/types"
-
-export const AnalyticsFeatureFlag: FeatureFlagTypes.FlagSettings = {
-  key: "analytics",
-  default_val: true,
-  env_key: "MEDUSA_FF_ANALYTICS",
-  description:
-    "Enable Medusa to collect data on usage, errors and performance for the purpose of improving the product",
-}

packages/core/utils/src/feature-flags/discover-feature-flags.ts

@@ -0,0 +1,70 @@
+import { FlagSettings } from "@medusajs/types"
+import { readdir } from "fs/promises"
+import { join, normalize } from "path"
+import { dynamicImport, isString, readDirRecursive } from "../common"
+
+const excludedFiles = ["index.js", "index.ts"]
+const excludedExtensions = [".d.ts", ".d.ts.map", ".js.map"]
+
+function isFeatureFlag(flag: unknown): flag is FlagSettings {
+  const f = flag as any
+  return !!f && isString(f.key) && isString(f.env_key)
+}
+
+/**
+ * Discover feature flag definitions from a directory and subdirectories
+ */
+export async function discoverFeatureFlagsFromDir(
+  sourcePath?: string,
+  maxDepth: number = 2
+): Promise<FlagSettings[]> {
+  if (!sourcePath) {
+    return []
+  }
+
+  const root = normalize(sourcePath)
+  const discovered: FlagSettings[] = []
+
+  const allEntries = await readDirRecursive(root, {
+    ignoreMissing: true,
+    maxDepth,
+  })
+
+  const featureFlagDirs = allEntries
+    .filter((e) => e.isDirectory() && e.name === "feature-flags")
+    .map((e) => join((e as any).path as string, e.name))
+
+  if (!featureFlagDirs.length) {
+    return discovered
+  }
+
+  await Promise.all(
+    featureFlagDirs.map(async (scanDir) => {
+      const entries = await readdir(scanDir, { withFileTypes: true })
+      await Promise.all(
+        entries.map(async (entry) => {
+          if (entry.isDirectory()) {
+            return
+          }
+
+          if (
+            excludedExtensions.some((ext) => entry.name.endsWith(ext)) ||
+            excludedFiles.includes(entry.name)
+          ) {
+            return
+          }
+
+          const fileExports = await dynamicImport(join(scanDir, entry.name))
+          const values = Object.values(fileExports)
+          for (const value of values) {
+            if (isFeatureFlag(value)) {
+              discovered.push(value)
+            }
+          }
+        })
+      )
+    })
+  )
+
+  return discovered
+}

packages/core/utils/src/feature-flags/flag-router.ts

@@ -1,5 +1,5 @@
 import { FeatureFlagTypes } from "@medusajs/types"
-import { isObject, isString } from "../../common"
+import { isObject, isString } from "../common"
 
 export class FlagRouter implements FeatureFlagTypes.IFlagRouter {
   private readonly flags: Record<string, boolean | Record<string, boolean>> = {}
@@ -75,3 +75,5 @@ export class FlagRouter implements FeatureFlagTypes.IFlagRouter {
     }))
   }
 }
+
+export const FeatureFlag = new FlagRouter({})

packages/core/utils/src/feature-flags/index.ts

@@ -1,10 +1,3 @@
-export * from "./analytics"
-export * from "./many-to-many-inventory"
-export * from "./medusa-v2"
-export * from "./order-editing"
-export * from "./product-categories"
-export * from "./publishable-api-keys"
-export * from "./sales-channels"
-export * from "./tax-inclusive-pricing"
-export * from "./utils"
-export * from "./workflows"
+export * from "./discover-feature-flags"
+export * from "./flag-router"
+export * from "./register-flag"

packages/core/utils/src/feature-flags/many-to-many-inventory.ts

@@ -1,9 +0,0 @@
-import { FeatureFlagTypes } from "@medusajs/types"
-
-export const ManyToManyInventoryFeatureFlag: FeatureFlagTypes.FlagSettings = {
-  key: "many_to_many_inventory",
-  default_val: false,
-  env_key: "MEDUSA_FF_MANY_TO_MANY_INVENTORY",
-  description:
-    "Enable capability to have many to many relationship between inventory items and variants",
-}

packages/core/utils/src/feature-flags/medusa-v2.ts

@@ -1,8 +0,0 @@
-import { FeatureFlagTypes } from "@medusajs/types"
-
-export const MedusaV2Flag: FeatureFlagTypes.FlagSettings = {
-  key: "medusa_v2",
-  default_val: false,
-  env_key: "MEDUSA_FF_MEDUSA_V2",
-  description: "[WIP] Enable Medusa V2",
-}

packages/core/utils/src/feature-flags/order-editing.ts

@@ -1,8 +0,0 @@
-import { FeatureFlagTypes } from "@medusajs/types"
-
-export const OrderEditingFeatureFlag: FeatureFlagTypes.FlagSettings = {
-  key: "order_editing",
-  default_val: true,
-  env_key: "MEDUSA_FF_ORDER_EDITING",
-  description: "[WIP] Enable the order editing feature",
-}

packages/core/utils/src/feature-flags/product-categories.ts

@@ -1,8 +0,0 @@
-import { FeatureFlagTypes } from "@medusajs/types"
-
-export const ProductCategoryFeatureFlag: FeatureFlagTypes.FlagSettings = {
-  key: "product_categories",
-  default_val: false,
-  env_key: "MEDUSA_FF_PRODUCT_CATEGORIES",
-  description: "[WIP] Enable the product categories feature",
-}

packages/core/utils/src/feature-flags/publishable-api-keys.ts

@@ -1,8 +0,0 @@
-import { FeatureFlagTypes } from "@medusajs/types"
-
-export const PublishableAPIKeysFeatureFlag: FeatureFlagTypes.FlagSettings = {
-  key: "publishable_api_keys",
-  default_val: true,
-  env_key: "MEDUSA_FF_PUBLISHABLE_API_KEYS",
-  description: "[WIP] Enable the publishable API keys feature",
-}

packages/core/utils/src/feature-flags/register-flag.ts

@@ -0,0 +1,66 @@
+import { FlagSettings, Logger } from "@medusajs/types"
+import {
+  isDefined,
+  isObject,
+  isString,
+  isTruthy,
+  objectFromStringPath,
+} from "../common"
+import { FlagRouter } from "./flag-router"
+
+export type RegisterFeatureFlagOptions = {
+  flag: FlagSettings
+  projectConfigFlags: Record<string, string | boolean | Record<string, boolean>>
+  router: FlagRouter
+  logger?: Logger
+  track?: (key: string) => void
+}
+
+/**
+ * Registers a feature flag on the provided router.
+ * Resolving precedence:
+ * - env overrides
+ * - project config overrides
+ * - default value
+ */
+export function registerFeatureFlag(options: RegisterFeatureFlagOptions) {
+  const { flag, projectConfigFlags, router, logger, track } = options
+
+  let value: boolean | Record<string, boolean> = isTruthy(flag.default_val)
+  let from: string | undefined
+
+  if (isDefined(process.env[flag.env_key])) {
+    from = "environment"
+    const envVal = process.env[flag.env_key]
+
+    value = isTruthy(envVal)
+
+    const parsedFromEnv = isString(envVal) ? envVal.split(",") : []
+    if (parsedFromEnv.length > 1) {
+      value = objectFromStringPath(parsedFromEnv)
+    }
+  } else if (isDefined(projectConfigFlags[flag.key])) {
+    from = "project config"
+
+    const pc = projectConfigFlags[flag.key] as string | boolean
+    value = isTruthy(pc)
+
+    if (isObject(projectConfigFlags[flag.key])) {
+      value = projectConfigFlags[flag.key] as Record<string, boolean>
+    }
+  }
+
+  if (logger && from) {
+    logger.info(
+      `Using flag ${flag.env_key} from ${from} with value ${JSON.stringify(
+        value
+      )}`
+    )
+  }
+
+  if (track && value === true) {
+    track(flag.key)
+  }
+
+  router.setFlag(flag.key, value)
+}

packages/core/utils/src/feature-flags/sales-channels.ts

@@ -1,8 +0,0 @@
-import { FeatureFlagTypes } from "@medusajs/types"
-
-export const SalesChannelFeatureFlag: FeatureFlagTypes.FlagSettings = {
-  key: "sales_channels",
-  default_val: true,
-  env_key: "MEDUSA_FF_SALES_CHANNELS",
-  description: "[WIP] Enable the sales channels feature",
-}

packages/core/utils/src/feature-flags/tax-inclusive-pricing.ts

@@ -1,8 +0,0 @@
-import { FeatureFlagTypes } from "@medusajs/types"
-
-export const TaxInclusivePricingFeatureFlag: FeatureFlagTypes.FlagSettings = {
-  key: "tax_inclusive_pricing",
-  default_val: false,
-  env_key: "MEDUSA_FF_TAX_INCLUSIVE_PRICING",
-  description: "[WIP] Enable tax inclusive pricing",
-}

packages/core/utils/src/feature-flags/utils/index.ts

@@ -1 +0,0 @@
-export * from "./flag-router"

packages/core/utils/src/feature-flags/workflows.ts

@@ -1,8 +0,0 @@
-import { FeatureFlagTypes } from "@medusajs/types"
-
-export const WorkflowsFeatureFlag: FeatureFlagTypes.FlagSettings = {
-  key: "workflows",
-  default_val: false,
-  env_key: "MEDUSA_FF_WORKFLOWS",
-  description: "[WIP] Enable workflows",
-}