@open-mercato/cli 0.6.7-develop.6552.1.5208a19369 → 0.6.7-develop.6565.1.1026d85fff

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.7-develop.6552.1.5208a19369",
+  "version": "0.6.7-develop.6565.1.1026d85fff",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,8 +60,8 @@
     "@mikro-orm/decorators": "^7.1.5",
     "@mikro-orm/migrations": "^7.1.5",
     "@mikro-orm/postgresql": "^7.1.5",
-    "@open-mercato/queue": "0.6.7-develop.6552.1.5208a19369",
-    "@open-mercato/shared": "0.6.7-develop.6552.1.5208a19369",
+    "@open-mercato/queue": "0.6.7-develop.6565.1.1026d85fff",
+    "@open-mercato/shared": "0.6.7-develop.6565.1.1026d85fff",
     "cross-spawn": "^7.0.6",
     "pg": "8.22.0",
     "semver": "^7.8.5",
@@ -71,10 +71,10 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.7-develop.6552.1.5208a19369"
+    "@open-mercato/shared": "0.6.7-develop.6565.1.1026d85fff"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.7-develop.6552.1.5208a19369",
+    "@open-mercato/shared": "0.6.7-develop.6565.1.1026d85fff",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

package/src/__tests__/mercato.test.ts

@@ -547,7 +547,11 @@ describe('generate post-step structural cache purge', () => {
   it('runs structural cache purge after successful generation when configs cache CLI is available', async () => {
     const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
     const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
-    const generateEntityIds = jest.fn().mockResolvedValue(undefined)
+    const generateEntityIds = jest.fn().mockResolvedValue({
+      filesWritten: ['/tmp/test-app/.mercato/generated/entities.ids.generated.ts'],
+      filesUnchanged: [],
+      errors: [],
+    })
     const generateModuleRegistry = jest.fn().mockResolvedValue(undefined)
     const generateModuleRegistryApp = jest.fn().mockResolvedValue(undefined)
     const generateModuleRegistryCli = jest.fn().mockResolvedValue(undefined)
@@ -594,10 +598,57 @@ describe('generate post-step structural cache purge', () => {
     consoleLogSpy.mockRestore()
   })
 
+  it('skips structural invalidation when every generated output is unchanged', async () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
+    const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
+    const unchangedResult = {
+      filesWritten: [],
+      filesUnchanged: ['/tmp/test-app/.mercato/generated/unchanged.generated.ts'],
+      errors: [],
+    }
+    const generators = {
+      generateEntityIds: jest.fn().mockResolvedValue(unchangedResult),
+      generateModuleRegistry: jest.fn().mockResolvedValue(unchangedResult),
+      generateModuleRegistryApp: jest.fn().mockResolvedValue(unchangedResult),
+      generateModuleRegistryCli: jest.fn().mockResolvedValue(unchangedResult),
+      generateModuleEntities: jest.fn().mockResolvedValue(unchangedResult),
+      generateModuleDi: jest.fn().mockResolvedValue(unchangedResult),
+      generateModulePackageSources: jest.fn().mockResolvedValue(unchangedResult),
+      generateOpenApi: jest.fn().mockResolvedValue(unchangedResult),
+    }
+    const bootstrapFromAppRoot = jest.fn()
+
+    jest.doMock('../lib/generators', () => generators)
+    jest.doMock('../lib/resolver', () => ({
+      createResolver: () => ({
+        getAppDir: () => '/tmp/test-app',
+      }),
+    }))
+    jest.doMock('@open-mercato/shared/lib/bootstrap/dynamicLoader', () => ({
+      bootstrapFromAppRoot,
+    }))
+
+    const mercato = await import('../mercato')
+    const exitCode = await mercato.run(['node', 'mercato', 'generate'])
+
+    expect(exitCode).toBe(0)
+    expect(bootstrapFromAppRoot).not.toHaveBeenCalled()
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      '[generate] Generated outputs unchanged; skipping structural cache purge.',
+    )
+
+    consoleErrorSpy.mockRestore()
+    consoleLogSpy.mockRestore()
+  })
+
   it('keeps generation successful when the post-generate cache purge bootstrap fails', async () => {
     const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation()
     const consoleLogSpy = jest.spyOn(console, 'log').mockImplementation()
-    const generateEntityIds = jest.fn().mockResolvedValue(undefined)
+    const generateEntityIds = jest.fn().mockResolvedValue({
+      filesWritten: ['/tmp/test-app/.mercato/generated/entities.ids.generated.ts'],
+      filesUnchanged: [],
+      errors: [],
+    })
     const generateModuleRegistry = jest.fn().mockResolvedValue(undefined)
     const generateModuleRegistryApp = jest.fn().mockResolvedValue(undefined)
     const generateModuleRegistryCli = jest.fn().mockResolvedValue(undefined)

package/src/lib/__integration__/TC-INT-008.spec.ts

@@ -282,28 +282,28 @@ test.describe('TC-INT-008: CLI agentic init mirrors standalone scaffolding asset
       expect(fs.existsSync(path.join(appDir, '.ai', 'skills', 'om-spec-writing'))).toBe(false)
       expect(fs.existsSync(path.join(appDir, 'scripts', 'install-skills.sh'))).toBe(true)
 
-      // install-skills.sh (run by agentic:init) replaces the legacy directory-level
-      // .claude/skills and .codex/skills symlinks with real directories holding one
-      // symlink per default-tier local skill; .cursor/skills keeps the directory link.
-      const cursorSkillsLinkPath = path.join(appDir, '.cursor', 'skills')
-      expect(fs.lstatSync(cursorSkillsLinkPath).isSymbolicLink()).toBe(true)
-      expect(normalizePath(fs.readlinkSync(cursorSkillsLinkPath))).toBe('../.ai/skills')
-
+      // install-skills.sh (run by agentic:init) installs every local tier skill once,
+      // into the canonical .agents/skills/. Codex and Cursor read that directory
+      // natively, so they get no skills directory of their own; Claude Code cannot,
+      // so it keeps a link layer pointing back at the canonical copy.
       const tiersManifest = JSON.parse(
         fs.readFileSync(path.join(agenticRoot, 'shared', 'ai', 'skills', 'tiers.json'), 'utf8'),
       ) as { default: string[]; tiers: Record<string, { skills: string[] }> }
       const defaultTierSkills = tiersManifest.default.flatMap((tierName) => tiersManifest.tiers[tierName].skills)
       expect(defaultTierSkills.length).toBeGreaterThan(0)
 
-      for (const toolDir of ['.claude', '.codex']) {
-        const harnessSkillsDir = path.join(appDir, toolDir, 'skills')
-        expect(fs.lstatSync(harnessSkillsDir).isDirectory()).toBe(true)
-        for (const skillName of defaultTierSkills) {
-          const skillLinkPath = path.join(harnessSkillsDir, skillName)
-          expect(fs.lstatSync(skillLinkPath).isSymbolicLink()).toBe(true)
-          expect(normalizePath(fs.readlinkSync(skillLinkPath))).toBe(`../../.ai/skills/${skillName}`)
-        }
+      for (const skillName of defaultTierSkills) {
+        const canonicalLinkPath = path.join(appDir, '.agents', 'skills', skillName)
+        expect(fs.lstatSync(canonicalLinkPath).isSymbolicLink()).toBe(true)
+        expect(normalizePath(fs.readlinkSync(canonicalLinkPath))).toBe(`../../.ai/skills/${skillName}`)
+
+        const claudeLinkPath = path.join(appDir, '.claude', 'skills', skillName)
+        expect(fs.lstatSync(claudeLinkPath).isSymbolicLink()).toBe(true)
+        expect(normalizePath(fs.readlinkSync(claudeLinkPath))).toBe(`../../.agents/skills/${skillName}`)
       }
+
+      expect(fs.existsSync(path.join(appDir, '.codex', 'skills'))).toBe(false)
+      expect(fs.existsSync(path.join(appDir, '.cursor', 'skills'))).toBe(false)
     } finally {
       fs.rmSync(tempRoot, { recursive: true, force: true })
     }

package/src/lib/__tests__/generate-watch-events.test.ts

@@ -0,0 +1,112 @@
+import path from 'node:path'
+import {
+  createGenerateWatchChangeSignal,
+  type GenerateWatchTarget,
+} from '../generate-watch-events'
+
+type RegisteredWatcher = {
+  target: GenerateWatchTarget
+  onChange: () => void
+  onError: () => void
+  close: jest.Mock
+}
+
+function createWatchHarness(initialTargets: GenerateWatchTarget[]) {
+  let targets = initialTargets
+  const registered: RegisteredWatcher[] = []
+  const watchDirectory = jest.fn((
+    target: GenerateWatchTarget,
+    onChange: () => void,
+    onError: () => void,
+  ) => {
+    const watcher = { target, onChange, onError, close: jest.fn() }
+    registered.push(watcher)
+    return watcher
+  })
+  const signal = createGenerateWatchChangeSignal({
+    getWatchTargets: () => targets,
+    watchDirectory,
+  })
+
+  return {
+    signal,
+    registered,
+    watchDirectory,
+    setTargets: (nextTargets: GenerateWatchTarget[]) => { targets = nextTargets },
+  }
+}
+
+describe('createGenerateWatchChangeSignal', () => {
+  it('deduplicates targets and increments its version on filesystem events', async () => {
+    const target = { directory: './modules', recursive: true }
+    const { signal, registered, watchDirectory } = createWatchHarness([target, target])
+
+    await signal.refresh()
+    expect(watchDirectory).toHaveBeenCalledTimes(1)
+    expect(registered[0].target.directory).toBe(path.resolve('./modules'))
+    expect(signal.currentVersion()).toBe(0)
+
+    registered[0].onChange()
+    registered[0].onChange()
+    expect(signal.currentVersion()).toBe(2)
+    expect(signal.usesPollingFallback()).toBe(false)
+  })
+
+  it('refreshes changed watch roots without recreating stable watchers', async () => {
+    const first = { directory: './modules-a', recursive: true }
+    const second = { directory: './modules-b', recursive: true }
+    const harness = createWatchHarness([first])
+
+    await harness.signal.refresh()
+    harness.setTargets([first, second])
+    await harness.signal.refresh()
+    expect(harness.watchDirectory).toHaveBeenCalledTimes(2)
+    expect(harness.registered[0].close).not.toHaveBeenCalled()
+
+    harness.setTargets([second])
+    await harness.signal.refresh()
+    expect(harness.registered[0].close).toHaveBeenCalledTimes(1)
+    expect(harness.registered[1].close).not.toHaveBeenCalled()
+  })
+
+  it('falls back to checksum polling when watcher setup fails', async () => {
+    const firstClose = jest.fn()
+    const watchDirectory = jest.fn()
+      .mockReturnValueOnce({ close: firstClose })
+      .mockImplementationOnce(() => { throw new Error('watch unavailable') })
+    const signal = createGenerateWatchChangeSignal({
+      getWatchTargets: () => [
+        { directory: './modules-a', recursive: true },
+        { directory: './modules-b', recursive: true },
+      ],
+      watchDirectory,
+    })
+
+    await signal.refresh()
+    expect(signal.usesPollingFallback()).toBe(true)
+    expect(signal.currentVersion()).toBe(1)
+    expect(firstClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('falls back to checksum polling when an active watcher errors', async () => {
+    const { signal, registered } = createWatchHarness([
+      { directory: './modules', recursive: true },
+    ])
+
+    await signal.refresh()
+    registered[0].onError()
+    expect(signal.usesPollingFallback()).toBe(true)
+    expect(registered[0].close).toHaveBeenCalledTimes(1)
+  })
+
+  it('closes filesystem watchers exactly once', async () => {
+    const { signal, registered } = createWatchHarness([
+      { directory: './modules', recursive: true },
+    ])
+
+    await signal.refresh()
+    await signal.close()
+    await signal.close()
+    expect(registered[0].close).toHaveBeenCalledTimes(1)
+  })
+})

package/src/lib/__tests__/generate-watch-structure.test.ts

@@ -77,4 +77,24 @@ describe('calculateGenerateWatchStructureChecksum', () => {
 
     expect(currentChecksum()).not.toBe(before)
   })
+
+  it('changes when a discovered worker is added and removed', () => {
+    const before = currentChecksum()
+    const workerPath = path.join(pkgModule, 'workers', 'sync-customers.ts')
+
+    write(workerPath, 'export default async function syncCustomers() {}\n')
+    const afterAdd = currentChecksum()
+    expect(afterAdd).not.toBe(before)
+
+    fs.rmSync(workerPath)
+    expect(currentChecksum()).toBe(before)
+  })
+
+  it('changes when the module registry configuration changes', () => {
+    const before = currentChecksum()
+
+    write(path.join(appDir, 'src', 'modules.ts'), 'export const enabledModules = ["customers"]\n')
+
+    expect(currentChecksum()).not.toBe(before)
+  })
 })

package/src/lib/__tests__/in-process-generate-watcher.test.ts

@@ -1,14 +1,32 @@
-import { startInProcessGenerateWatcher } from '../in-process-generate-watcher'
+import {
+  startInProcessGenerateWatcher,
+  type GenerateWatcherChangeSignal,
+} from '../in-process-generate-watcher'
 
 const silentLogger = { log: jest.fn(), error: jest.fn() }
 
 async function flushAsync(times = 5): Promise<void> {
   for (let i = 0; i < times; i++) {
-    // eslint-disable-next-line no-await-in-loop
     await Promise.resolve()
   }
 }
 
+function createFakeChangeSignal() {
+  let version = 0
+  let fallback = false
+  const signal: GenerateWatcherChangeSignal = {
+    currentVersion: () => version,
+    refresh: jest.fn(async () => undefined),
+    usesPollingFallback: () => fallback,
+    close: jest.fn(async () => undefined),
+  }
+  return {
+    signal,
+    markChanged: () => { version += 1 },
+    usePollingFallback: () => { fallback = true },
+  }
+}
+
 describe('startInProcessGenerateWatcher', () => {
   beforeEach(() => {
     jest.useFakeTimers()
@@ -97,6 +115,179 @@ describe('startInProcessGenerateWatcher', () => {
     await handle.done
   })
 
+  it('does not recompute the full checksum during event-gated idle polls', async () => {
+    const runGenerators = jest.fn(async () => undefined)
+    const computeStructureChecksum = jest.fn(async () => 'stable')
+    const { signal } = createFakeChangeSignal()
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: true,
+      quiet: true,
+      logger: silentLogger,
+      changeSignal: signal,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+    expect(computeStructureChecksum).toHaveBeenCalledTimes(1)
+
+    for (let poll = 0; poll < 20; poll += 1) {
+      jest.advanceTimersByTime(1000)
+      await flushAsync(8)
+    }
+
+    expect(computeStructureChecksum).toHaveBeenCalledTimes(1)
+    expect(runGenerators).not.toHaveBeenCalled()
+    await handle.close()
+  })
+
+  it('coalesces filesystem event bursts into one checksum and regeneration', async () => {
+    let currentChecksum = 'before'
+    const runGenerators = jest.fn(async () => undefined)
+    const computeStructureChecksum = jest.fn(async () => currentChecksum)
+    const { signal, markChanged } = createFakeChangeSignal()
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: true,
+      quiet: true,
+      logger: silentLogger,
+      changeSignal: signal,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+    currentChecksum = 'after'
+    markChanged()
+    markChanged()
+    markChanged()
+    jest.advanceTimersByTime(1000)
+    await flushAsync(12)
+
+    expect(computeStructureChecksum).toHaveBeenCalledTimes(2)
+    expect(runGenerators).toHaveBeenCalledTimes(1)
+    expect(runGenerators).toHaveBeenCalledWith('structure change')
+    await handle.close()
+  })
+
+  it('validates an unrelated filesystem event without regenerating', async () => {
+    const runGenerators = jest.fn(async () => undefined)
+    const computeStructureChecksum = jest.fn(async () => 'stable')
+    const { signal, markChanged } = createFakeChangeSignal()
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: true,
+      quiet: true,
+      logger: silentLogger,
+      changeSignal: signal,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+    markChanged()
+    jest.advanceTimersByTime(1000)
+    await flushAsync(12)
+
+    expect(computeStructureChecksum).toHaveBeenCalledTimes(2)
+    expect(runGenerators).not.toHaveBeenCalled()
+    await handle.close()
+  })
+
+  it('retries a dirty checksum after a transient checksum failure', async () => {
+    const runGenerators = jest.fn(async () => undefined)
+    const computeStructureChecksum = jest.fn()
+      .mockResolvedValueOnce('before')
+      .mockRejectedValueOnce(new Error('temporary read failure'))
+      .mockResolvedValue('after')
+    const { signal, markChanged } = createFakeChangeSignal()
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: true,
+      quiet: true,
+      logger: silentLogger,
+      changeSignal: signal,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+    markChanged()
+    jest.advanceTimersByTime(1000)
+    await flushAsync(8)
+    expect(runGenerators).not.toHaveBeenCalled()
+
+    jest.advanceTimersByTime(1000)
+    await flushAsync(12)
+    expect(computeStructureChecksum).toHaveBeenCalledTimes(3)
+    expect(runGenerators).toHaveBeenCalledTimes(1)
+    await handle.close()
+  })
+
+  it('keeps an event that arrives while a checksum is in flight dirty for the next poll', async () => {
+    let releaseChecksum: ((value: string) => void) | null = null
+    const runGenerators = jest.fn(async () => undefined)
+    const computeStructureChecksum = jest.fn()
+      .mockResolvedValueOnce('before')
+      .mockImplementationOnce(() => new Promise<string>((resolve) => {
+        releaseChecksum = resolve
+      }))
+      .mockResolvedValue('after')
+    const { signal, markChanged } = createFakeChangeSignal()
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: true,
+      quiet: true,
+      logger: silentLogger,
+      changeSignal: signal,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+    markChanged()
+    jest.advanceTimersByTime(1000)
+    await flushAsync(8)
+    expect(computeStructureChecksum).toHaveBeenCalledTimes(2)
+
+    markChanged()
+    releaseChecksum?.('after')
+    await flushAsync(12)
+    expect(runGenerators).toHaveBeenCalledTimes(1)
+
+    jest.advanceTimersByTime(1000)
+    await flushAsync(12)
+    expect(computeStructureChecksum).toHaveBeenCalledTimes(3)
+    await handle.close()
+  })
+
+  it('falls back to full checksum polling when filesystem watching is unavailable', async () => {
+    const runGenerators = jest.fn(async () => undefined)
+    const computeStructureChecksum = jest.fn(async () => 'stable')
+    const { signal, usePollingFallback } = createFakeChangeSignal()
+    usePollingFallback()
+    const handle = startInProcessGenerateWatcher({
+      pollMs: 1000,
+      skipInitial: true,
+      quiet: true,
+      logger: silentLogger,
+      changeSignal: signal,
+      computeStructureChecksum,
+      runGenerators,
+    })
+
+    await flushAsync(8)
+    jest.advanceTimersByTime(1000)
+    await flushAsync(8)
+    jest.advanceTimersByTime(1000)
+    await flushAsync(8)
+
+    expect(computeStructureChecksum).toHaveBeenCalledTimes(3)
+    await handle.close()
+    expect(signal.close).toHaveBeenCalledTimes(1)
+  })
+
   it('does not start a new poll while a regeneration is in flight', async () => {
     let release: (() => void) | null = null
     const runGenerators = jest.fn(async (_reason: string) => {

package/src/lib/agentic-setup.ts

@@ -409,8 +409,8 @@ function generateCodex(config: AgenticConfig): void {
 
   copyFile(srcDir, 'mcp.json.example', join(targetDir, '.codex', 'mcp.json.example'))
 
-  // Symlink .codex/skills → ../.ai/skills
-  ensureSkillsLink(join(targetDir, '.codex', 'skills'), join('..', '.ai', 'skills'))
+  // No .codex/skills directory: Codex reads the canonical .agents/skills/,
+  // which scripts/install-skills.sh populates.
 }
 
 function generateCursor(config: AgenticConfig): void {
@@ -424,8 +424,8 @@ function generateCursor(config: AgenticConfig): void {
   copyFile(srcDir, 'hooks/entity-migration-check.mjs', join(targetDir, '.cursor', 'hooks', 'entity-migration-check.mjs'))
   copyFile(srcDir, 'mcp.json.example', join(targetDir, '.cursor', 'mcp.json.example'))
 
-  // Symlink .cursor/skills → ../.ai/skills
-  ensureSkillsLink(join(targetDir, '.cursor', 'skills'), join('..', '.ai', 'skills'))
+  // No .cursor/skills directory: Cursor reads the canonical .agents/skills/,
+  // which scripts/install-skills.sh populates.
 }
 
 function ensureSkillsLink(linkPath: string, target: string): void {
@@ -518,6 +518,7 @@ export async function runAgenticSetup(
   if (selectedIds.includes('codex')) generateCodex(config)
   if (selectedIds.includes('cursor')) generateCursor(config)
 
+  persistAgentSelection(targetDir, selectedIds)
   installSkills(targetDir)
 
   console.log('')
@@ -539,6 +540,24 @@ export async function runAgenticSetup(
   console.log('')
 }
 
+/**
+ * Persist the agent selection so later `yarn install-skills` runs keep honoring
+ * it: agents the user did not pick go into `agents.ignore` in tiers.json and
+ * never get a skills directory of their own.
+ */
+function persistAgentSelection(targetDir: string, selectedIds: string[]): void {
+  const manifestPath = join(targetDir, '.ai', 'skills', 'tiers.json')
+  if (!existsSync(manifestPath)) return
+  const ignore = SELECTABLE.map((tool) => tool.id).filter((id) => !selectedIds.includes(id))
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8')) as Record<string, unknown>
+  if (ignore.length > 0) {
+    manifest.agents = { ignore }
+  } else {
+    delete manifest.agents
+  }
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+}
+
 function installSkills(targetDir: string): void {
   const installScript = join(targetDir, 'scripts', 'install-skills.sh')
   if (!existsSync(installScript)) return

package/src/lib/generate-watch-events.ts

@@ -0,0 +1,125 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { GenerateWatcherChangeSignal } from './in-process-generate-watcher'
+
+export type GenerateWatchTarget = {
+  directory: string
+  recursive: boolean
+  fileName?: string
+}
+
+type WatchHandle = {
+  close(): void
+}
+
+type WatchDirectory = (
+  target: GenerateWatchTarget,
+  onChange: (fileName?: string) => void,
+  onError: () => void,
+) => WatchHandle
+
+export type GenerateWatchChangeSignalOptions = {
+  getWatchTargets: () => Promise<GenerateWatchTarget[]> | GenerateWatchTarget[]
+  watchDirectory?: WatchDirectory
+}
+
+function targetKey(target: GenerateWatchTarget): string {
+  return JSON.stringify([
+    path.resolve(target.directory),
+    target.recursive,
+    target.fileName ?? '',
+  ])
+}
+
+const defaultWatchDirectory: WatchDirectory = (target, onChange, onError) => {
+  const watcher = fs.watch(
+    target.directory,
+    { recursive: target.recursive },
+    (_eventType, fileName) => {
+      const normalizedName = String(fileName ?? '')
+      if (target.fileName && normalizedName && normalizedName !== target.fileName) return
+      onChange(normalizedName || undefined)
+    },
+  )
+  watcher.on('error', onError)
+  return watcher
+}
+
+export function createGenerateWatchChangeSignal(
+  options: GenerateWatchChangeSignalOptions,
+): GenerateWatcherChangeSignal {
+  const watchDirectory = options.watchDirectory ?? defaultWatchDirectory
+  const watchers = new Map<string, WatchHandle>()
+  let version = 0
+  let pollingFallback = false
+  let closed = false
+
+  const closeWatchers = () => {
+    for (const watcher of watchers.values()) {
+      try { watcher.close() } catch {}
+    }
+    watchers.clear()
+  }
+
+  const enterPollingFallback = () => {
+    if (pollingFallback) return
+    pollingFallback = true
+    version += 1
+    closeWatchers()
+  }
+
+  return {
+    currentVersion: () => version,
+    usesPollingFallback: () => pollingFallback,
+    refresh: async () => {
+      if (closed || pollingFallback) return
+
+      let targets: GenerateWatchTarget[]
+      try {
+        targets = await options.getWatchTargets()
+      } catch {
+        enterPollingFallback()
+        return
+      }
+
+      const normalizedTargets = new Map<string, GenerateWatchTarget>()
+      for (const target of targets) {
+        const normalized: GenerateWatchTarget = {
+          ...target,
+          directory: path.resolve(target.directory),
+        }
+        normalizedTargets.set(targetKey(normalized), normalized)
+      }
+
+      for (const [key, watcher] of watchers) {
+        if (normalizedTargets.has(key)) continue
+        try { watcher.close() } catch {}
+        watchers.delete(key)
+      }
+
+      for (const [key, target] of normalizedTargets) {
+        if (watchers.has(key)) continue
+        try {
+          const watcher = watchDirectory(
+            target,
+            () => { version += 1 },
+            enterPollingFallback,
+          )
+          if (closed || pollingFallback) {
+            try { watcher.close() } catch {}
+            continue
+          }
+          watchers.set(key, watcher)
+        } catch {
+          enterPollingFallback()
+          return
+        }
+      }
+    },
+    close: () => {
+      if (closed) return
+      closed = true
+      closeWatchers()
+    },
+  }
+}