@open-mercato/cli 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3045.b4b3320cc2

package/src/lib/generators/extensions/ai-agents.ts

@@ -0,0 +1,240 @@
+import { VariableDeclarationKind, type WriterFunction } from 'ts-morph'
+import type { GeneratorExtension } from '../extension'
+import {
+  arrayLiteral,
+  arrowFunction,
+  binaryExpression,
+  identifier,
+  methodCall,
+  objectLiteral,
+  parenthesized,
+  propertyAccess,
+  writeValue,
+} from '../ast'
+import {
+  emptyArray,
+  emptyObject,
+  moduleEntry,
+  namespaceFallback,
+  namespaceImportSpec,
+  renderGeneratedTsSource,
+} from './shared'
+
+/**
+ * Generator extension for `<module>/ai-agents.ts` files.
+ *
+ * Each module's `ai-agents.ts` may export both base agent contributions
+ * (`aiAgents`), additive extensions for existing agents
+ * (`aiAgentExtensions`), AND cross-module override declarations
+ * (`aiAgentOverrides`). The generator scans the file once, emits the
+ * configuration entry with all fields, and produces filtered
+ * exports inside `ai-agents.generated.ts`:
+ *
+ *   - `aiAgentConfigEntries` (entries that declare base agents)
+ *   - `aiAgentExtensionEntries` / `allAiAgentExtensions` (entries that append to agents)
+ *   - `aiAgentOverrideEntries` (entries that declare overrides)
+ *
+ * The runtime (`@open-mercato/ai-assistant`) reads
+ * `aiAgentConfigEntries` to populate the agent registry,
+ * `aiAgentOverrideEntries` to apply cross-module replacements, and
+ * `allAiAgentExtensions` to append safe metadata after the base load. See spec
+ * `.ai/specs/2026-04-30-ai-overrides-and-module-disable.md`.
+ */
+export function createAiAgentsExtension(): GeneratorExtension {
+  const imports = [] as Array<ReturnType<typeof namespaceImportSpec>>
+  const entries: WriterFunction[] = []
+
+  return {
+    id: 'registry.ai-agents',
+    outputFiles: ['ai-agents.generated.ts'],
+    scanModule(ctx) {
+      ctx.processStandaloneConfig({
+        roots: ctx.roots,
+        imps: ctx.imps,
+        modId: ctx.moduleId,
+        relativePath: 'ai-agents.ts',
+        prefix: 'AI_AGENTS',
+        importIdRef: ctx.importIdRef,
+        standaloneImports: imports,
+        standaloneEntries: entries,
+        writeConfig: ({ importName, moduleId }) =>
+          moduleEntry(moduleId, [
+            {
+              name: 'agents',
+              value: namespaceFallback({
+                importName,
+                members: ['aiAgents', 'default'],
+                fallback: emptyArray(),
+                castType: 'unknown[]',
+              }),
+            },
+            {
+              name: 'overrides',
+              value: namespaceFallback({
+                importName,
+                members: ['aiAgentOverrides'],
+                fallback: emptyObject(),
+                castType: 'Record<string, unknown>',
+              }),
+            },
+            {
+              name: 'extensions',
+              value: namespaceFallback({
+                importName,
+                members: ['aiAgentExtensions'],
+                fallback: emptyArray(),
+                castType: 'unknown[]',
+              }),
+            },
+          ]),
+      })
+    },
+    generateOutput() {
+      const output = renderGeneratedTsSource({
+        fileName: 'ai-agents.generated.ts',
+        imports,
+        build(sourceFile) {
+          sourceFile.addTypeAlias({
+            name: 'AiAgentConfigEntry',
+            type: '{ moduleId: string; agents: unknown[]; overrides: Record<string, unknown>; extensions: unknown[] }',
+          })
+          sourceFile.addTypeAlias({
+            name: 'AiAgentOverrideConfigEntry',
+            type: '{ moduleId: string; overrides: Record<string, unknown> }',
+          })
+          sourceFile.addTypeAlias({
+            name: 'AiAgentExtensionConfigEntry',
+            type: '{ moduleId: string; extensions: unknown[] }',
+          })
+          sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            declarations: [
+              {
+                name: 'aiAgentConfigEntriesRaw',
+                type: 'AiAgentConfigEntry[]',
+                initializer: arrayLiteral(entries, writeValue),
+              },
+            ],
+          })
+          sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            isExported: true,
+            declarations: [
+              {
+                name: 'aiAgentConfigEntries',
+                type: 'AiAgentConfigEntry[]',
+                initializer: methodCall(identifier('aiAgentConfigEntriesRaw'), 'filter', [
+                  arrowFunction({
+                    parameters: ['entry'],
+                    body: binaryExpression(propertyAccess(propertyAccess(identifier('entry'), 'agents'), 'length'), '>', 0),
+                  }),
+                ]),
+              },
+            ],
+          })
+          sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            isExported: true,
+            declarations: [
+              {
+                name: 'aiAgentExtensionEntries',
+                type: 'AiAgentExtensionConfigEntry[]',
+                initializer: methodCall(
+                  methodCall(identifier('aiAgentConfigEntriesRaw'), 'filter', [
+                    arrowFunction({
+                      parameters: ['entry'],
+                      body: binaryExpression(propertyAccess(propertyAccess(identifier('entry'), 'extensions'), 'length'), '>', 0),
+                    }),
+                  ]),
+                  'map',
+                  [
+                    arrowFunction({
+                      parameters: ['entry'],
+                      body: parenthesized(
+                        objectLiteral([
+                          { name: 'moduleId', value: propertyAccess(identifier('entry'), 'moduleId') },
+                          { name: 'extensions', value: propertyAccess(identifier('entry'), 'extensions') },
+                        ]),
+                      ),
+                    }),
+                  ],
+                ),
+              },
+            ],
+          })
+          sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            isExported: true,
+            declarations: [
+              {
+                name: 'allAiAgentExtensions',
+                initializer: methodCall(identifier('aiAgentExtensionEntries'), 'flatMap', [
+                  arrowFunction({
+                    parameters: ['entry'],
+                    body: propertyAccess(identifier('entry'), 'extensions'),
+                  }),
+                ]),
+              },
+            ],
+          })
+          sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            isExported: true,
+            declarations: [
+              {
+                name: 'allAiAgents',
+                initializer: methodCall(identifier('aiAgentConfigEntries'), 'flatMap', [
+                  arrowFunction({
+                    parameters: ['entry'],
+                    body: propertyAccess(identifier('entry'), 'agents'),
+                  }),
+                ]),
+              },
+            ],
+          })
+          sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            isExported: true,
+            declarations: [
+              {
+                name: 'aiAgentOverrideEntries',
+                type: 'AiAgentOverrideConfigEntry[]',
+                initializer: methodCall(
+                  methodCall(identifier('aiAgentConfigEntriesRaw'), 'filter', [
+                    arrowFunction({
+                      parameters: ['entry'],
+                      body: binaryExpression(
+                        propertyAccess(
+                          methodCall(identifier('Object'), 'keys', [
+                            propertyAccess(identifier('entry'), 'overrides'),
+                          ]),
+                          'length',
+                        ),
+                        '>',
+                        0,
+                      ),
+                    }),
+                  ]),
+                  'map',
+                  [
+                    arrowFunction({
+                      parameters: ['entry'],
+                      body: parenthesized(
+                        objectLiteral([
+                          { name: 'moduleId', value: propertyAccess(identifier('entry'), 'moduleId') },
+                          { name: 'overrides', value: propertyAccess(identifier('entry'), 'overrides') },
+                        ]),
+                      ),
+                    }),
+                  ],
+                ),
+              },
+            ],
+          })
+        },
+      })
+
+      return new Map([['ai-agents.generated.ts', output]])
+    },
+  }
+}

package/src/lib/generators/extensions/ai-tools.ts

@@ -6,17 +6,36 @@ import {
   binaryExpression,
   identifier,
   methodCall,
+  objectLiteral,
+  parenthesized,
   propertyAccess,
   writeValue,
 } from '../ast'
 import {
   emptyArray,
+  emptyObject,
   moduleEntry,
   namespaceFallback,
   namespaceImportSpec,
   renderGeneratedTsSource,
 } from './shared'
 
+/**
+ * Generator extension for `<module>/ai-tools.ts` files.
+ *
+ * Each module's `ai-tools.ts` may export both base tool contributions
+ * (`aiTools`) AND cross-module override declarations (`aiToolOverrides`).
+ * The generator scans the file once and emits two filtered exports
+ * inside `ai-tools.generated.ts`:
+ *
+ *   - `aiToolConfigEntries` (entries that declare base tools)
+ *   - `aiToolOverrideEntries` (entries that declare overrides)
+ *
+ * The runtime (`@open-mercato/ai-assistant`) reads `aiToolConfigEntries`
+ * to populate the tool registry and `aiToolOverrideEntries` to apply
+ * cross-module replacements after the base load. See spec
+ * `.ai/specs/2026-04-30-ai-overrides-and-module-disable.md`.
+ */
 export function createAiToolsExtension(): GeneratorExtension {
   const imports = [] as Array<ReturnType<typeof namespaceImportSpec>>
   const entries: WriterFunction[] = []
@@ -45,6 +64,15 @@ export function createAiToolsExtension(): GeneratorExtension {
                 castType: 'unknown[]',
               }),
             },
+            {
+              name: 'overrides',
+              value: namespaceFallback({
+                importName,
+                members: ['aiToolOverrides'],
+                fallback: emptyObject(),
+                castType: 'Record<string, unknown>',
+              }),
+            },
           ]),
       })
     },
@@ -55,7 +83,11 @@ export function createAiToolsExtension(): GeneratorExtension {
         build(sourceFile) {
           sourceFile.addTypeAlias({
             name: 'AiToolConfigEntry',
-            type: '{ moduleId: string; tools: unknown[] }',
+            type: '{ moduleId: string; tools: unknown[]; overrides: Record<string, unknown> }',
+          })
+          sourceFile.addTypeAlias({
+            name: 'AiToolOverrideConfigEntry',
+            type: '{ moduleId: string; overrides: Record<string, unknown> }',
           })
           sourceFile.addVariableStatement({
             declarationKind: VariableDeclarationKind.Const,
@@ -98,6 +130,45 @@ export function createAiToolsExtension(): GeneratorExtension {
               },
             ],
           })
+          sourceFile.addVariableStatement({
+            declarationKind: VariableDeclarationKind.Const,
+            isExported: true,
+            declarations: [
+              {
+                name: 'aiToolOverrideEntries',
+                type: 'AiToolOverrideConfigEntry[]',
+                initializer: methodCall(
+                  methodCall(identifier('aiToolConfigEntriesRaw'), 'filter', [
+                    arrowFunction({
+                      parameters: ['entry'],
+                      body: binaryExpression(
+                        propertyAccess(
+                          methodCall(identifier('Object'), 'keys', [
+                            propertyAccess(identifier('entry'), 'overrides'),
+                          ]),
+                          'length',
+                        ),
+                        '>',
+                        0,
+                      ),
+                    }),
+                  ]),
+                  'map',
+                  [
+                    arrowFunction({
+                      parameters: ['entry'],
+                      body: parenthesized(
+                        objectLiteral([
+                          { name: 'moduleId', value: propertyAccess(identifier('entry'), 'moduleId') },
+                          { name: 'overrides', value: propertyAccess(identifier('entry'), 'overrides') },
+                        ]),
+                      ),
+                    }),
+                  ],
+                ),
+              },
+            ],
+          })
         },
       })
 

package/src/lib/generators/extensions/index.ts

@@ -1,4 +1,5 @@
 import type { GeneratorExtension } from '../extension'
+import { createAiAgentsExtension } from './ai-agents'
 import { createAiToolsExtension } from './ai-tools'
 import { createAnalyticsExtension } from './analytics'
 import { createCommandInterceptorsExtension } from './command-interceptors'
@@ -22,6 +23,7 @@ export function loadGeneratorExtensions(): GeneratorExtension[] {
     createNotificationsExtension(),
     createMessagesExtension(),
     createAiToolsExtension(),
+    createAiAgentsExtension(),
     createEventsExtension(),
     createAnalyticsExtension(),
     createTranslatableFieldsExtension(),

package/src/lib/testing/__tests__/integration-discovery.test.ts

@@ -12,10 +12,20 @@ async function writeTestFile(projectRoot: string, relativePath: string, content
 describe('integration discovery', () => {
   let tempRoot = ''
   const previousEnterpriseFlag = process.env.OM_ENABLE_ENTERPRISE_MODULES
+  const testEnvKeys = [
+    'OM_TEST_DISCOVERY_AI_KEY',
+    'OM_TEST_DISCOVERY_FALLBACK_AI_KEY',
+    'OM_TEST_DISCOVERY_REQUIRED_KEY',
+  ] as const
+  const previousTestEnvValues = new Map<string, string | undefined>()
 
   beforeEach(async () => {
     tempRoot = await mkdtemp(path.join(os.tmpdir(), 'om-integration-discovery-'))
     delete process.env.OM_ENABLE_ENTERPRISE_MODULES
+    for (const key of testEnvKeys) {
+      previousTestEnvValues.set(key, process.env[key])
+      delete process.env[key]
+    }
   })
 
   afterEach(async () => {
@@ -27,6 +37,15 @@ describe('integration discovery', () => {
     } else {
       process.env.OM_ENABLE_ENTERPRISE_MODULES = previousEnterpriseFlag
     }
+    for (const key of testEnvKeys) {
+      const previousValue = previousTestEnvValues.get(key)
+      if (previousValue === undefined) {
+        delete process.env[key]
+      } else {
+        process.env[key] = previousValue
+      }
+    }
+    previousTestEnvValues.clear()
   })
 
   it('applies folder and per-test metadata dependencies', async () => {
@@ -139,4 +158,53 @@ describe('integration discovery', () => {
       'node_modules/@open-mercato/core/src/modules/customers/__integration__/TC-CRM-020.spec.ts',
     ])
   })
+
+  it('applies folder and per-test metadata environment requirements', async () => {
+    await writeTestFile(tempRoot, 'packages/ai-assistant/src/modules/ai_assistant/.gitkeep')
+    await writeTestFile(
+      tempRoot,
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/TC-AI-001.spec.ts',
+      'export {}\n',
+    )
+    await writeTestFile(
+      tempRoot,
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/TC-AI-002.spec.ts',
+      'export {}\n',
+    )
+    await writeTestFile(
+      tempRoot,
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/TC-AI-002.meta.ts',
+      "export const integrationMeta = { requiredAnyEnvVars: ['OM_TEST_DISCOVERY_AI_KEY', 'OM_TEST_DISCOVERY_FALLBACK_AI_KEY'] }\n",
+    )
+    await writeTestFile(
+      tempRoot,
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/live/meta.ts',
+      "export const integrationMeta = { requiredEnvVars: ['OM_TEST_DISCOVERY_REQUIRED_KEY'] }\n",
+    )
+    await writeTestFile(
+      tempRoot,
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/live/TC-AI-003.spec.ts',
+      'export {}\n',
+    )
+
+    let discovered = discoverIntegrationSpecFiles(tempRoot, path.join(tempRoot, '.ai', 'qa', 'tests'))
+    expect(discovered.map((entry) => entry.path)).toEqual([
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/TC-AI-001.spec.ts',
+    ])
+
+    process.env.OM_TEST_DISCOVERY_FALLBACK_AI_KEY = 'test-key'
+    discovered = discoverIntegrationSpecFiles(tempRoot, path.join(tempRoot, '.ai', 'qa', 'tests'))
+    expect(discovered.map((entry) => entry.path)).toEqual([
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/TC-AI-001.spec.ts',
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/TC-AI-002.spec.ts',
+    ])
+
+    process.env.OM_TEST_DISCOVERY_REQUIRED_KEY = 'required-key'
+    discovered = discoverIntegrationSpecFiles(tempRoot, path.join(tempRoot, '.ai', 'qa', 'tests'))
+    expect(discovered.map((entry) => entry.path)).toEqual([
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/live/TC-AI-003.spec.ts',
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/TC-AI-001.spec.ts',
+      'packages/ai-assistant/src/modules/ai_assistant/__integration__/TC-AI-002.spec.ts',
+    ])
+  })
 })

package/src/lib/testing/integration-discovery.ts

@@ -6,6 +6,8 @@ export type IntegrationSpecDiscoveryItem = {
   moduleName: string | null
   isOverlay: boolean
   requiredModules: string[]
+  requiredEnvVars: string[]
+  requiredAnyEnvVars: string[]
 }
 
 const MODULE_INTEGRATION_DIRECTORY_NAME = '__integration__'
@@ -26,6 +28,8 @@ const DISCOVERY_IGNORED_DIRS = new Set([
 ])
 const INTEGRATION_META_FILE_NAMES = ['meta.ts', 'index.ts'] as const
 const INTEGRATION_META_DEPENDENCY_KEYS = ['dependsOnModules', 'requiredModules', 'requiresModules'] as const
+const INTEGRATION_META_REQUIRED_ENV_KEYS = ['requiredEnvVars', 'requiresEnvVars'] as const
+const INTEGRATION_META_REQUIRED_ANY_ENV_KEYS = ['requiredAnyEnvVars', 'requiresAnyEnvVars'] as const
 const DEFAULT_OVERLAY_ROOT = 'packages/enterprise'
 
 export function normalizePath(filePath: string): string {
@@ -160,15 +164,15 @@ function isOverlayIntegrationPath(relativePath: string, overlayRoot: string): bo
   return normalizePath(relativePath).startsWith(`${normalizePath(overlayRoot)}/`)
 }
 
-function extractDependencyListFromSource(source: string): string[] {
+function extractStringArrayFromSource(source: string, keys: readonly string[]): string[] {
   const collected = new Set<string>()
-  for (const key of INTEGRATION_META_DEPENDENCY_KEYS) {
+  for (const key of keys) {
     const keyPattern = new RegExp(`${key}\\s*:\\s*\\[([\\s\\S]*?)\\]`, 'm')
     const keyMatch = source.match(keyPattern)
     if (!keyMatch?.[1]) continue
     const valuesPattern = /['"`]([a-zA-Z0-9_.-]+)['"`]/g
     for (const valueMatch of keyMatch[1].matchAll(valuesPattern)) {
-      const value = normalizeModuleId(valueMatch[1] ?? '')
+      const value = String(valueMatch[1] ?? '').trim()
       if (value) {
         collected.add(value)
       }
@@ -177,6 +181,18 @@ function extractDependencyListFromSource(source: string): string[] {
   return Array.from(collected)
 }
 
+function extractDependencyListFromSource(source: string): string[] {
+  return extractStringArrayFromSource(source, INTEGRATION_META_DEPENDENCY_KEYS).map(normalizeModuleId)
+}
+
+function extractRequiredEnvVarsFromSource(source: string): string[] {
+  return extractStringArrayFromSource(source, INTEGRATION_META_REQUIRED_ENV_KEYS)
+}
+
+function extractRequiredAnyEnvVarsFromSource(source: string): string[] {
+  return extractStringArrayFromSource(source, INTEGRATION_META_REQUIRED_ANY_ENV_KEYS)
+}
+
 function readDependenciesFromMetadataFile(absolutePath: string): string[] {
   try {
     return extractDependencyListFromSource(readFileSync(absolutePath, 'utf8'))
@@ -185,6 +201,22 @@ function readDependenciesFromMetadataFile(absolutePath: string): string[] {
   }
 }
 
+function readRequiredEnvVarsFromMetadataFile(absolutePath: string): string[] {
+  try {
+    return extractRequiredEnvVarsFromSource(readFileSync(absolutePath, 'utf8'))
+  } catch {
+    return []
+  }
+}
+
+function readRequiredAnyEnvVarsFromMetadataFile(absolutePath: string): string[] {
+  try {
+    return extractRequiredAnyEnvVarsFromSource(readFileSync(absolutePath, 'utf8'))
+  } catch {
+    return []
+  }
+}
+
 function resolveIntegrationRootDirectory(relativeSpecPath: string): string | null {
   const segments = normalizePath(relativeSpecPath).split('/')
   const integrationDirectoryIndex = segments.indexOf(MODULE_INTEGRATION_DIRECTORY_NAME)
@@ -231,6 +263,85 @@ function resolveRequiredModulesForSpec(projectRoot: string, relativeSpecPath: st
   return Array.from(requiredModules)
 }
 
+function resolveRequiredEnvVarsForSpec(projectRoot: string, relativeSpecPath: string): string[] {
+  const requiredEnvVars = new Set<string>()
+  const normalizedSpecPath = normalizePath(relativeSpecPath)
+  const absoluteSpecPath = path.join(projectRoot, normalizedSpecPath)
+  const integrationRoot = resolveIntegrationRootDirectory(normalizedSpecPath)
+
+  if (integrationRoot) {
+    const relativeDirectory = normalizePath(path.dirname(normalizedSpecPath))
+    const integrationRootAbsolute = path.join(projectRoot, integrationRoot)
+    const directoryAbsolute = path.join(projectRoot, relativeDirectory)
+    const relativeFromIntegrationRoot = normalizePath(path.relative(integrationRootAbsolute, directoryAbsolute))
+    const pathSegments = relativeFromIntegrationRoot === '.'
+      ? []
+      : relativeFromIntegrationRoot.split('/').filter(Boolean)
+
+    let currentDirectory = integrationRootAbsolute
+    const traversal = [currentDirectory, ...pathSegments.map((segment) => {
+      currentDirectory = path.join(currentDirectory, segment)
+      return currentDirectory
+    })]
+
+    for (const directoryPath of traversal) {
+      for (const metadataFileName of INTEGRATION_META_FILE_NAMES) {
+        const metadataPath = path.join(directoryPath, metadataFileName)
+        readRequiredEnvVarsFromMetadataFile(metadataPath).forEach((envVar) => requiredEnvVars.add(envVar))
+      }
+    }
+  }
+
+  readRequiredEnvVarsFromMetadataFile(absoluteSpecPath).forEach((envVar) => requiredEnvVars.add(envVar))
+  const specFileName = path.basename(normalizedSpecPath, '.spec.ts')
+  const perTestMetadataPath = path.join(path.dirname(absoluteSpecPath), `${specFileName}.meta.ts`)
+  readRequiredEnvVarsFromMetadataFile(perTestMetadataPath).forEach((envVar) => requiredEnvVars.add(envVar))
+
+  return Array.from(requiredEnvVars)
+}
+
+function resolveRequiredAnyEnvVarsForSpec(projectRoot: string, relativeSpecPath: string): string[] {
+  const requiredAnyEnvVars = new Set<string>()
+  const normalizedSpecPath = normalizePath(relativeSpecPath)
+  const absoluteSpecPath = path.join(projectRoot, normalizedSpecPath)
+  const integrationRoot = resolveIntegrationRootDirectory(normalizedSpecPath)
+
+  if (integrationRoot) {
+    const relativeDirectory = normalizePath(path.dirname(normalizedSpecPath))
+    const integrationRootAbsolute = path.join(projectRoot, integrationRoot)
+    const directoryAbsolute = path.join(projectRoot, relativeDirectory)
+    const relativeFromIntegrationRoot = normalizePath(path.relative(integrationRootAbsolute, directoryAbsolute))
+    const pathSegments = relativeFromIntegrationRoot === '.'
+      ? []
+      : relativeFromIntegrationRoot.split('/').filter(Boolean)
+
+    let currentDirectory = integrationRootAbsolute
+    const traversal = [currentDirectory, ...pathSegments.map((segment) => {
+      currentDirectory = path.join(currentDirectory, segment)
+      return currentDirectory
+    })]
+
+    for (const directoryPath of traversal) {
+      for (const metadataFileName of INTEGRATION_META_FILE_NAMES) {
+        const metadataPath = path.join(directoryPath, metadataFileName)
+        readRequiredAnyEnvVarsFromMetadataFile(metadataPath).forEach((envVar) => requiredAnyEnvVars.add(envVar))
+      }
+    }
+  }
+
+  readRequiredAnyEnvVarsFromMetadataFile(absoluteSpecPath).forEach((envVar) => requiredAnyEnvVars.add(envVar))
+  const specFileName = path.basename(normalizedSpecPath, '.spec.ts')
+  const perTestMetadataPath = path.join(path.dirname(absoluteSpecPath), `${specFileName}.meta.ts`)
+  readRequiredAnyEnvVarsFromMetadataFile(perTestMetadataPath).forEach((envVar) => requiredAnyEnvVars.add(envVar))
+
+  return Array.from(requiredAnyEnvVars)
+}
+
+function isEnvironmentVariableConfigured(name: string): boolean {
+  const value = process.env[name]
+  return typeof value === 'string' && value.trim().length > 0
+}
+
 export function discoverIntegrationSpecFiles(projectRoot: string, legacyIntegrationRoot: string): IntegrationSpecDiscoveryItem[] {
   const discoveredByPath = new Map<string, IntegrationSpecDiscoveryItem>()
   const overlayRoot = resolveOverlayRootPath()
@@ -249,6 +360,8 @@ export function discoverIntegrationSpecFiles(projectRoot: string, legacyIntegrat
       moduleName: extractModuleNameFromIntegrationPath(relativePath),
       isOverlay: isOverlayIntegrationPath(relativePath, overlayRoot),
       requiredModules: resolveRequiredModulesForSpec(projectRoot, relativePath),
+      requiredEnvVars: resolveRequiredEnvVarsForSpec(projectRoot, relativePath),
+      requiredAnyEnvVars: resolveRequiredAnyEnvVarsForSpec(projectRoot, relativePath),
     })
   }
 
@@ -261,6 +374,8 @@ export function discoverIntegrationSpecFiles(projectRoot: string, legacyIntegrat
           moduleName: extractModuleNameFromIntegrationPath(relativePath),
           isOverlay: isOverlayIntegrationPath(relativePath, overlayRoot),
           requiredModules: resolveRequiredModulesForSpec(projectRoot, relativePath),
+          requiredEnvVars: resolveRequiredEnvVarsForSpec(projectRoot, relativePath),
+          requiredAnyEnvVars: resolveRequiredAnyEnvVarsForSpec(projectRoot, relativePath),
         })
       }
     }
@@ -280,6 +395,15 @@ export function discoverIntegrationSpecFiles(projectRoot: string, legacyIntegrat
       if (file.requiredModules.some((moduleId) => !enabledModules.has(normalizeModuleId(moduleId)))) {
         return false
       }
+      if (file.requiredEnvVars.some((envVar) => !isEnvironmentVariableConfigured(envVar))) {
+        return false
+      }
+      if (
+        file.requiredAnyEnvVars.length > 0 &&
+        !file.requiredAnyEnvVars.some((envVar) => isEnvironmentVariableConfigured(envVar))
+      ) {
+        return false
+      }
       if (!file.isOverlay) {
         return true
       }