@open-mercato/cli 0.5.1-develop.3032.01699048cb → 0.5.1-develop.3043.1a796c3920

package/src/lib/__tests__/dev-env-reload.test.ts

@@ -0,0 +1,62 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createDevEnvReloader, resolveDevEnvFilePaths } from '../dev-env-reload'
+
+describe('dev env reload helpers', () => {
+  let appDir: string
+
+  beforeEach(() => {
+    appDir = fs.mkdtempSync(path.join(os.tmpdir(), 'om-dev-env-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(appDir, { recursive: true, force: true })
+  })
+
+  it('resolves app env files in low-to-high dev precedence order', () => {
+    expect(resolveDevEnvFilePaths('/tmp/app')).toEqual([
+      '/tmp/app/.env',
+      '/tmp/app/.env.development',
+      '/tmp/app/.env.local',
+      '/tmp/app/.env.development.local',
+    ])
+  })
+
+  it('reloads changed app env files without overriding shell-provided values', () => {
+    fs.writeFileSync(path.join(appDir, '.env'), [
+      'APP_URL=http://env.example',
+      'DATABASE_URL=postgres://env-database',
+      'REMOVED_LATER=present',
+    ].join('\n'))
+    fs.writeFileSync(path.join(appDir, '.env.local'), [
+      'APP_URL=http://local.example',
+      'SHELL_VALUE=env-file-value',
+    ].join('\n'))
+
+    const environment: NodeJS.ProcessEnv = {
+      SHELL_VALUE: 'shell-value',
+    }
+    const reloader = createDevEnvReloader(appDir, environment, Object.entries(environment))
+
+    reloader.reload()
+
+    expect(environment.APP_URL).toBe('http://local.example')
+    expect(environment.DATABASE_URL).toBe('postgres://env-database')
+    expect(environment.SHELL_VALUE).toBe('shell-value')
+    expect(environment.REMOVED_LATER).toBe('present')
+
+    fs.writeFileSync(path.join(appDir, '.env'), [
+      'APP_URL=http://env.example',
+      'DATABASE_URL=postgres://changed-database',
+    ].join('\n'))
+    fs.rmSync(path.join(appDir, '.env.local'))
+
+    reloader.reload()
+
+    expect(environment.APP_URL).toBe('http://env.example')
+    expect(environment.DATABASE_URL).toBe('postgres://changed-database')
+    expect(environment.SHELL_VALUE).toBe('shell-value')
+    expect(environment.REMOVED_LATER).toBeUndefined()
+  })
+})

package/src/lib/dev-env-reload.ts

@@ -0,0 +1,110 @@
+import dotenv from 'dotenv'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const DEV_ENV_PRIORITY = [
+  '.env',
+  '.env.development',
+  '.env.local',
+  '.env.development.local',
+] as const
+
+export type DevEnvReloader = {
+  reload: () => void
+  getWatchedFiles: () => string[]
+}
+
+export function resolveDevEnvFilePaths(appDir: string): string[] {
+  return DEV_ENV_PRIORITY.map((fileName) => path.join(appDir, fileName))
+}
+
+export function createDevEnvReloader(
+  appDir: string,
+  environment: NodeJS.ProcessEnv = process.env,
+  baseEnvironmentEntries: Iterable<[string, string | undefined]> = Object.entries(environment),
+): DevEnvReloader {
+  const baseEnvironment = new Map<string, string | undefined>(
+    Array.from(baseEnvironmentEntries, ([key, value]) => [key, value]),
+  )
+  const managedKeys = new Set<string>()
+  const envFilePaths = resolveDevEnvFilePaths(appDir)
+
+  const resetManagedKeys = () => {
+    for (const key of managedKeys) {
+      const baseValue = baseEnvironment.get(key)
+      if (baseValue === undefined) {
+        delete environment[key]
+      } else {
+        environment[key] = baseValue
+      }
+    }
+    managedKeys.clear()
+  }
+
+  const reload = () => {
+    resetManagedKeys()
+
+    for (const envFilePath of envFilePaths) {
+      if (!fs.existsSync(envFilePath)) continue
+
+      const parsed = dotenv.parse(fs.readFileSync(envFilePath))
+      for (const [key, value] of Object.entries(parsed)) {
+        if (baseEnvironment.has(key) && baseEnvironment.get(key) !== undefined) {
+          continue
+        }
+        environment[key] = value
+        managedKeys.add(key)
+      }
+    }
+  }
+
+  return {
+    reload,
+    getWatchedFiles: () => [...envFilePaths],
+  }
+}
+
+export function watchDevEnvFiles(
+  appDir: string,
+  onChange: (filePath: string) => void,
+  options: { debounceMs?: number } = {},
+): () => void {
+  const debounceMs = options.debounceMs ?? 250
+  const envFilePaths = resolveDevEnvFilePaths(appDir)
+  const timers = new Map<string, NodeJS.Timeout>()
+  const watchers = envFilePaths.map((envFilePath) => {
+    const watchDir = path.dirname(envFilePath)
+    const watchFileName = path.basename(envFilePath)
+
+    if (!fs.existsSync(watchDir)) return null
+
+    try {
+      return fs.watch(watchDir, (eventType, fileName) => {
+        if (eventType !== 'change' && eventType !== 'rename') return
+        if (String(fileName ?? '') !== watchFileName) return
+
+        const existingTimer = timers.get(envFilePath)
+        if (existingTimer) {
+          clearTimeout(existingTimer)
+        }
+
+        timers.set(envFilePath, setTimeout(() => {
+          timers.delete(envFilePath)
+          onChange(envFilePath)
+        }, debounceMs))
+      })
+    } catch {
+      return null
+    }
+  }).filter((watcher): watcher is fs.FSWatcher => watcher !== null)
+
+  return () => {
+    for (const timer of timers.values()) {
+      clearTimeout(timer)
+    }
+    timers.clear()
+    for (const watcher of watchers) {
+      watcher.close()
+    }
+  }
+}

package/src/lib/generators/__tests__/module-subset.test.ts

@@ -1383,6 +1383,7 @@ describe('all generated files are valid with varying subsets', () => {
       'search.generated.ts',
       'notifications.generated.ts',
       'ai-tools.generated.ts',
+      'ai-agents.generated.ts',
       'events.generated.ts',
       'analytics.generated.ts',
       'translations-fields.generated.ts',
@@ -1441,6 +1442,19 @@ describe('all generated files are valid with varying subsets', () => {
     expect(aiTools).not.toContain('no_ai')
   })
 
+  it('ai-agents.generated.ts is empty when no module provides ai-agents.ts', async () => {
+    scaffoldModule(tmpDir, 'no_ai_agents', 'pkg', ['setup.ts'])
+    const resolver = createMockResolver(tmpDir, [
+      { id: 'no_ai_agents', from: '@open-mercato/core' },
+    ])
+    await generateModuleRegistry({ resolver, quiet: true })
+
+    const aiAgents = readGenerated(tmpDir, 'ai-agents.generated.ts')!
+    expect(aiAgents).toContain('export const aiAgentConfigEntries')
+    expect(aiAgents).toContain('export const allAiAgents')
+    expect(aiAgents).not.toContain('no_ai_agents')
+  })
+
   it('security generated registries are empty when no module provides security convention files', async () => {
     scaffoldModule(tmpDir, 'no_security', 'pkg', ['setup.ts'])
     touchFile(

package/src/lib/generators/__tests__/output-snapshots.test.ts

@@ -370,6 +370,22 @@ export default aiTools
 `,
   )
 
+  // -- AI agents --
+  touchFile(
+    pkgModulePath('orders', 'ai-agents.ts'),
+    `export const aiAgents = [
+  {
+    id: 'orders.assistant',
+    module: 'orders',
+    displayName: 'Orders Assistant',
+    allowedTools: ['list_orders'],
+    readOnly: true,
+  },
+]
+export default aiAgents
+`,
+  )
+
   // -- Frontend middleware --
   touchFile(
     pkgModulePath('orders', 'frontend', 'middleware.ts'),
@@ -652,6 +668,7 @@ function captureGeneratedFiles(): Map<string, string> {
 describe('generator output compatibility', () => {
   const registryFiles = [
     'ai-tools.generated.ts',
+    'ai-agents.generated.ts',
     'analytics.generated.ts',
     'api-routes.generated.ts',
     'backend-middleware.generated.ts',

package/src/lib/generators/__tests__/scanner.test.ts

@@ -380,7 +380,7 @@ describe('resolveModuleFile', () => {
   it('app override takes precedence for all convention files', () => {
     const conventionFiles = [
       'acl.ts', 'ce.ts', 'search.ts', 'notifications.ts',
-      'ai-tools.ts', 'events.ts', 'analytics.ts', 'setup.ts',
+      'ai-tools.ts', 'ai-agents.ts', 'events.ts', 'analytics.ts', 'setup.ts',
       'translations.ts', 'security.mfa-providers.ts', 'security.sudo.ts',
       'data/extensions.ts', 'data/fields.ts',
     ]

package/src/lib/generators/__tests__/structural-contracts.test.ts

@@ -209,6 +209,7 @@ function scaffoldFixture(): ModuleEntry[] {
   touchFile(pkgModulePath('orders', 'inbox-actions.ts'), `export const inboxActions = [\n  { type: 'orders.approve', id: 'orders.approve-order', label: 'Approve Order', icon: 'check', description: 'Approve pending', async execute(a: any) { return { ok: true } } },\n]\nexport default inboxActions\n`)
   touchFile(pkgModulePath('orders', 'analytics.ts'), `export const analyticsConfig = {\n  entities: [{ entityId: 'orders:sales_order', requiredFeatures: ['orders.view'], entityConfig: { tableName: 'sales_orders', dateField: 'created_at' }, fieldMappings: { id: { dbColumn: 'id', type: 'uuid' } } }],\n}\nexport default analyticsConfig\n`)
   touchFile(pkgModulePath('orders', 'ai-tools.ts'), `export const aiTools = [\n  { name: 'list_orders', description: 'List recent orders', inputSchema: {}, requiredFeatures: ['orders.view'] },\n]\nexport default aiTools\n`)
+  touchFile(pkgModulePath('orders', 'ai-agents.ts'), `export const aiAgents = [\n  { id: 'orders.assistant', module: 'orders', displayName: 'Orders Assistant', allowedTools: ['list_orders'], readOnly: true },\n]\nexport default aiAgents\n`)
   touchFile(pkgModulePath('orders', 'frontend', 'middleware.ts'), `export const middleware = [\n  { id: 'orders.auth-check', pattern: '/orders/**', handler: async (req: any) => req },\n]\nexport default middleware\n`)
   touchFile(pkgModulePath('orders', 'backend', 'middleware.ts'), `export const middleware = [\n  { id: 'orders.admin-check', pattern: '/backend/orders/**', handler: async (req: any) => req },\n]\nexport default middleware\n`)
   touchFile(pkgModulePath('orders', 'message-types.ts'), `export const messageTypes = [\n  { type: 'orders.order_confirmation', module: 'orders', labelKey: 'orders.messages.confirmation.label', icon: 'mail', color: 'blue', allowReply: false, allowForward: true },\n]\nexport default messageTypes\n`)
@@ -937,6 +938,31 @@ describe('ai-tools.generated.ts', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// ai-agents.generated.ts
+// ---------------------------------------------------------------------------
+
+describe('ai-agents.generated.ts', () => {
+  let content: string
+
+  beforeEach(async () => {
+    const enabled = scaffoldFixture()
+    const resolver = createMockResolver(enabled)
+    await generateModuleRegistry({ resolver, quiet: true })
+    content = readGenerated('ai-agents.generated.ts')
+  })
+
+  it('exports filtered entries and flattened allAiAgents', () => {
+    expect(content).toContain('export const aiAgentConfigEntries')
+    expect(content).toContain('export const allAiAgents')
+  })
+
+  it('has orders module entry with agents property', () => {
+    expectModuleIds(content, ['orders'])
+    expect(content).toContain('agents:')
+  })
+})
+
 // ---------------------------------------------------------------------------
 // translations-fields.generated.ts
 // ---------------------------------------------------------------------------

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(),