@tnotesjs/core 0.2.1 → 0.2.2

package/services/file-watcher/renameDetector.ts

@@ -0,0 +1,120 @@
+/**
+ * services/file-watcher/renameDetector.ts
+ *
+ * 文件夹重命名/删除检测
+ */
+
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+import { NoteManager } from '../../core/NoteManager'
+
+import type { Logger } from '../../utils'
+
+const FOLDER_RENAME_DETECT_WINDOW_MS = 500
+
+interface RenameDetectorDeps {
+  /** 笔记目录路径 */
+  notesDir: string
+  /** 目录缓存操作 */
+  dirCache: {
+    has: (name: string) => boolean
+    add: (name: string) => void
+    delete: (name: string) => void
+  }
+  /** 日志记录器 */
+  logger: Logger
+}
+
+interface RenameDetectorCallbacks {
+  /** 笔记删除事件回调 */
+  onDelete: (oldName: string) => void
+  /** 笔记重命名事件回调 */
+  onRename: (oldName: string, newName: string) => void
+}
+
+interface RenameDetectorConfig
+  extends RenameDetectorDeps, RenameDetectorCallbacks {}
+
+export interface PendingRename {
+  oldName: string
+  time: number
+}
+
+export class RenameDetector {
+  /** 待处理的文件夹重命名 */
+  private pendingFolderRename: PendingRename | null = null
+
+  /** 文件夹重命名检测定时器 */
+  private folderRenameTimer: NodeJS.Timeout | null = null
+
+  constructor(private config: RenameDetectorConfig) {}
+
+  handleFsRename(folderName: string) {
+    const { notesDir, dirCache, logger, onDelete, onRename } = this.config
+
+    const folderPath = join(notesDir, folderName)
+    const folderExists = existsSync(folderPath)
+    const noteIndex = NoteManager.extractNoteIndex(folderName)
+    if (!noteIndex) {
+      logger.warn(`无法从文件夹名称提取笔记索引: ${folderName}`)
+      return
+    }
+
+    if (!folderExists) {
+      // 第一次收到“删除”，先假设是重命名的起点，延迟一段时间再决策
+      if (dirCache.has(folderName)) {
+        logger.info(`检测到文件夹删除/重命名: ${folderName}`)
+        this.pendingFolderRename = { oldName: folderName, time: Date.now() }
+        if (this.folderRenameTimer) clearTimeout(this.folderRenameTimer)
+        this.folderRenameTimer = setTimeout(() => {
+          if (this.pendingFolderRename) {
+            logger.warn(`检测到笔记删除: ${this.pendingFolderRename.oldName}`)
+            onDelete(this.pendingFolderRename.oldName)
+          }
+          this.pendingFolderRename = null
+          this.folderRenameTimer = null
+        }, FOLDER_RENAME_DETECT_WINDOW_MS)
+      }
+      return
+    }
+
+    // folder exists
+    if (!dirCache.has(folderName)) {
+      logger.info(`检测到文件夹创建/重命名: ${folderName}`)
+      if (
+        this.pendingFolderRename &&
+        Date.now() - this.pendingFolderRename.time <
+          FOLDER_RENAME_DETECT_WINDOW_MS
+      ) {
+        const oldName = this.pendingFolderRename.oldName
+        const oldNoteIndex = NoteManager.extractNoteIndex(oldName)
+        if (oldNoteIndex && oldNoteIndex === noteIndex) {
+          logger.info(`检测到文件夹重命名: ${oldName} → ${folderName}`)
+          if (this.folderRenameTimer) {
+            clearTimeout(this.folderRenameTimer)
+            this.folderRenameTimer = null
+          }
+          onRename(oldName, folderName)
+          this.pendingFolderRename = null
+        } else if (oldNoteIndex && oldNoteIndex !== noteIndex) {
+          logger.warn(`索引冲突，回退: ${oldName} -> ${folderName}`)
+        }
+      }
+
+      // 新文件夹：无论是否匹配 rename，都把目录缓存补上，必要时移除旧目录
+      dirCache.add(folderName)
+      if (this.pendingFolderRename) {
+        dirCache.delete(this.pendingFolderRename.oldName)
+      }
+    }
+  }
+
+  clearTimers() {
+    if (this.folderRenameTimer) {
+      clearTimeout(this.folderRenameTimer)
+      this.folderRenameTimer = null
+    }
+    this.pendingFolderRename = null
+  }
+}

package/services/file-watcher/service.ts

@@ -0,0 +1,352 @@
+/**
+ * services/file-watcher/service.ts
+ *
+ * 文件监听服务
+ *
+ * - 监听笔记文件标题的变化并自动更新 toc
+ * - 监听笔记配置文件的变化并自动更新笔记的状态
+ */
+
+import { request as httpRequest } from 'http'
+
+import { ConfigChangeHandler } from './configChangeHandler'
+import { EventScheduler } from './eventScheduler'
+import { FolderChangeHandler } from './folderChangeHandler'
+import { FsWatcherAdapter } from './fsWatcherAdapter'
+import { GlobalUpdateCoordinator } from './globalUpdateCoordinator'
+import { safeExecute } from './internal'
+import { WATCH_EVENT_TYPES } from './internal'
+import { ReadmeChangeHandler } from './readmeChangeHandler'
+import { RenameDetector } from './renameDetector'
+import { WatchState } from './watchState'
+import { NOTES_DIR_PATH, port, repoName } from '../../config/constants'
+import { NoteIndexCache } from '../../core/NoteIndexCache'
+import { logger } from '../../utils'
+import { NoteService } from '../note/service'
+import { ReadmeService } from '../readme/service'
+import { TocService } from '../toc/service'
+
+import type { WatchEvent } from './internal'
+
+const NOTES_DIR_NOT_SET_ERROR = 'NOTES_DIR_PATH 未设置，无法启动文件监听'
+
+const UPDATE_UNLOCK_DELAY_MS = 500
+
+/** vite 端 fileWatcherBridgePlugin 暴露的 broadcast 接口路径 */
+const RENAME_BROADCAST_PATH = '/__tnotes_broadcast_rename'
+const SEARCH_REINDEX_PATH = '/__tnotes_search_reindex'
+
+export class FileWatcherService {
+  private static instance: FileWatcherService | null = null
+
+  private watchState!: WatchState
+  private scheduler!: EventScheduler
+  private renameDetector!: RenameDetector
+  private configHandler!: ConfigChangeHandler
+  private readmeHandler!: ReadmeChangeHandler
+  private coordinator!: GlobalUpdateCoordinator
+  private folderHandler!: FolderChangeHandler
+  private adapter!: FsWatcherAdapter
+  private noteService!: NoteService
+  private readmeService!: ReadmeService
+  private tocService!: TocService
+  private noteIndexCache!: NoteIndexCache
+  private unlockTimer: NodeJS.Timeout | null = null
+
+  constructor(private notesDir: string = NOTES_DIR_PATH) {
+    if (!this.notesDir) {
+      throw new Error(NOTES_DIR_NOT_SET_ERROR)
+    }
+    this.init()
+    FileWatcherService.instance = this
+  }
+
+  static getInstance(): FileWatcherService | null {
+    return FileWatcherService.instance
+  }
+
+  private init(): void {
+    this.noteService = NoteService.getInstance()
+    this.readmeService = ReadmeService.getInstance()
+    this.tocService = TocService.getInstance()
+    this.noteIndexCache = NoteIndexCache.getInstance()
+
+    this.watchState = this.initWatchState()
+    this.scheduler = this.initScheduler()
+    this.folderHandler = this.initFolderHandler()
+    this.renameDetector = this.initRenameDetector()
+    this.configHandler = this.initConfigHandler()
+    this.readmeHandler = this.initReadmeHandler()
+    this.coordinator = this.initCoordinator()
+    this.adapter = this.initAdapter()
+  }
+
+  private initWatchState(): WatchState {
+    const watchState = new WatchState({ notesDir: this.notesDir, logger })
+    watchState.initializeFromDisk()
+    return watchState
+  }
+
+  private initScheduler(): EventScheduler {
+    return new EventScheduler({
+      onFlush: (events) => this.handleFileChange(events),
+      onPauseForBatch: () => logger.warn('监听服务暂停 3s 等待批量更新完成...'),
+      onResumeAfterBatch: () => logger.info('恢复自动监听'),
+      reinit: () => this.watchState.initializeFromDisk(),
+    })
+  }
+
+  private initFolderHandler(): FolderChangeHandler {
+    return new FolderChangeHandler({
+      notesDir: this.notesDir,
+      watchState: this.watchState,
+      scheduler: this.scheduler,
+      noteService: this.noteService,
+      readmeService: this.readmeService,
+      tocService: this.tocService,
+      noteIndexCache: this.noteIndexCache,
+      logger,
+      onRenameSuccess: (payload) => {
+        // file-watcher 进程与 Vite dev server 进程不同，无法直接调 ws.send。
+        // 通过 HTTP 调 vite 子进程暴露的 broadcast 接口，由其转发为 WS 事件。
+        void this.broadcastRename(payload)
+      },
+      onNoteStructureChanged: (reason) => {
+        void this.broadcastSearchReindex(reason)
+      },
+    })
+  }
+
+  private async broadcastSearchReindex(reason: string): Promise<void> {
+    const path = `/${repoName}${SEARCH_REINDEX_PATH}`
+    const body = JSON.stringify({ reason })
+    const hosts = ['127.0.0.1', '::1']
+
+    let lastError: unknown = null
+    for (const host of hosts) {
+      try {
+        await this.postOnce(host, path, body)
+        return
+      } catch (error) {
+        lastError = error
+      }
+    }
+    logger.warn(
+      `广播搜索索引重建失败 (POST http://[127.0.0.1|::1]:${port}${path}): ${String(lastError)}`,
+    )
+  }
+
+  private async broadcastRename(payload: {
+    oldFolder: string
+    newFolder: string
+    noteIndex: string
+  }): Promise<void> {
+    // 注意：用 Node 原生 http.request，而不是 Node 18 的全局 fetch。
+    // Windows 上 undici fetch 在某些 Node 18.x 版本下访问 127.0.0.1 偶发报
+    // `TypeError: fetch failed` (cause 通常是 ECONNREFUSED 错误传递异常)。
+    // http.request 的行为更可预期，且不依赖 Happy Eyeballs / DNS。
+    //
+    // 另外：Vite dev server 默认 host=`localhost`，在 Node 18 + Windows 下
+    // 可能仅绑定到 IPv6 `::1` 而非 IPv4 `127.0.0.1`，所以这里依次尝试两者。
+    const path = `/${repoName}${RENAME_BROADCAST_PATH}`
+    const body = JSON.stringify(payload)
+    const hosts = ['127.0.0.1', '::1']
+
+    let lastError: unknown = null
+    for (const host of hosts) {
+      try {
+        await this.postOnce(host, path, body)
+        return
+      } catch (error) {
+        lastError = error
+      }
+    }
+    logger.warn(
+      `广播重命名事件失败 (POST http://[127.0.0.1|::1]:${port}${path}): ${String(lastError)}`,
+    )
+  }
+
+  private postOnce(host: string, path: string, body: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const req = httpRequest(
+        {
+          host,
+          port,
+          path,
+          method: 'POST',
+          family: host.includes(':') ? 6 : 4,
+          headers: {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(body),
+          },
+        },
+        (res) => {
+          // 消费响应体，确保 socket 被释放
+          res.on('data', () => {})
+          res.on('end', () => {
+            if (res.statusCode && res.statusCode >= 400) {
+              reject(new Error(`HTTP ${res.statusCode}`))
+              return
+            }
+            resolve()
+          })
+        },
+      )
+      req.on('error', reject)
+      req.write(body)
+      req.end()
+    })
+  }
+
+  private initRenameDetector(): RenameDetector {
+    return new RenameDetector({
+      notesDir: this.notesDir,
+      dirCache: {
+        has: (name) => this.watchState.hasNoteDir(name),
+        add: (name) => this.watchState.addNoteDir(name),
+        delete: (name) => this.watchState.deleteNoteDir(name),
+      },
+      logger,
+      onDelete: (oldName) => this.folderHandler.handleFolderDeletion(oldName),
+      onRename: (oldName, newName) =>
+        this.folderHandler.handleFolderRenameUpdate(oldName, newName),
+    })
+  }
+
+  private initConfigHandler(): ConfigChangeHandler {
+    return new ConfigChangeHandler({
+      state: this.watchState,
+      noteService: this.noteService,
+      noteIndexCache: this.noteIndexCache,
+      logger,
+    })
+  }
+
+  private initReadmeHandler(): ReadmeChangeHandler {
+    return new ReadmeChangeHandler({ noteService: this.noteService })
+  }
+
+  private initCoordinator(): GlobalUpdateCoordinator {
+    return new GlobalUpdateCoordinator({
+      readmeService: this.readmeService,
+      tocService: this.tocService,
+      noteIndexCache: this.noteIndexCache,
+      logger,
+    })
+  }
+
+  private initAdapter(): FsWatcherAdapter {
+    return new FsWatcherAdapter({
+      notesDir: this.notesDir,
+      isUpdating: () => this.scheduler.getUpdating(),
+      onRename: (folderName) => this.renameDetector.handleFsRename(folderName),
+      onNoteEvent: (event) => this.onNoteEvent(event),
+      logger,
+    })
+  }
+
+  start(): void {
+    this.watchState.initializeFromDisk()
+    this.adapter.start()
+  }
+
+  stop(): void {
+    this.adapter.stop()
+    this.scheduler.clearTimers()
+    this.renameDetector.clearTimers()
+    this.folderHandler.clearTimers()
+    if (this.unlockTimer) {
+      clearTimeout(this.unlockTimer)
+      this.unlockTimer = null
+    }
+    logger.info('文件监听服务已停止')
+  }
+
+  pause(): void {
+    this.scheduler.setUpdating(true)
+    logger.info('文件监听已暂停')
+  }
+
+  resume(): void {
+    this.watchState.initializeFromDisk()
+    this.scheduler.setUpdating(false)
+    logger.info('文件监听已恢复')
+  }
+
+  isWatching(): boolean {
+    return this.adapter.isWatching()
+  }
+
+  /**
+   * 挂起文件监听（关闭 fs.watch 句柄），用于需要操作文件夹的场景（如重命名）
+   * Windows 上 fs.watch 会锁住文件夹句柄，必须先关闭才能重命名
+   */
+  suspend(): void {
+    this.adapter.stop()
+    this.scheduler.setUpdating(true)
+    logger.info('文件监听已挂起（fs.watch 已关闭）')
+  }
+
+  /**
+   * 恢复文件监听（重新启动 fs.watch）
+   */
+  unsuspend(): void {
+    this.watchState.initializeFromDisk()
+    this.scheduler.setUpdating(false)
+    this.adapter.start()
+    logger.info('文件监听已恢复（fs.watch 已重启）')
+  }
+
+  // #region - 私有实现
+
+  private onNoteEvent(event: WatchEvent): void {
+    if (!this.isNoteFile(event.path)) return
+    if (!this.watchState.updateFileHash(event.path)) return
+    if (this.scheduler.recordChangeAndDetectBatch()) return
+    this.scheduler.enqueue(event)
+  }
+
+  private async handleFileChange(events: WatchEvent[]): Promise<void> {
+    try {
+      // 优先处理配置状态变更；仅当配置未变更时再处理 README 内容更新
+      const configChanges = events.filter(
+        (e) => e.type === WATCH_EVENT_TYPES.CONFIG,
+      )
+      const readmeChanges = events.filter(
+        (e) => e.type === WATCH_EVENT_TYPES.README,
+      )
+
+      const changedNoteIndexes = await this.configHandler.handle(configChanges)
+
+      if (changedNoteIndexes.length > 0) {
+        await safeExecute(
+          '配置变更更新',
+          () => this.coordinator.applyConfigUpdates(changedNoteIndexes),
+          logger,
+        )
+        return
+      }
+
+      await safeExecute(
+        'README 变更更新',
+        async () => {
+          await this.readmeHandler.handle(readmeChanges)
+          await this.coordinator.updateNoteReadmesOnly(events)
+        },
+        logger,
+      )
+    } finally {
+      if (this.unlockTimer) clearTimeout(this.unlockTimer)
+      this.unlockTimer = setTimeout(() => {
+        this.unlockTimer = null
+        this.scheduler.setUpdating(false)
+      }, UPDATE_UNLOCK_DELAY_MS)
+    }
+  }
+
+  private isNoteFile(filePath: string): boolean {
+    return filePath.endsWith('README.md') || filePath.endsWith('.tnotes.json')
+  }
+
+  // #endregion - 私有实现
+}

package/services/file-watcher/watchState.ts

@@ -0,0 +1,194 @@
+/**
+ * services/file-watcher/watchState.ts
+ *
+ * 监听状态存储：哈希缓存、配置缓存、目录缓存
+ */
+
+import { createHash } from 'crypto'
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join } from 'path'
+
+import type { ConfigSnapshot } from './internal'
+import type { NoteConfig } from '../../types'
+import type { Logger } from '../../utils'
+
+interface WatchStateConfig {
+  /** 笔记目录路径 */
+  notesDir: string
+  /** 日志记录器 */
+  logger: Logger
+}
+
+export class WatchState {
+  /** 文件哈希缓存 */
+  private fileHashes = new Map<string, string>()
+
+  /** 笔记目录缓存 */
+  private noteDirCache = new Set<string>()
+
+  /** 笔记配置缓存 */
+  private configCache = new Map<string, ConfigSnapshot>()
+
+  constructor(private config: WatchStateConfig) {}
+
+  /**
+   * 获取指定文件的 MD5 哈希值，若文件不存在或读取失败返回 null
+   *
+   * @param filePath 文件路径
+   * @returns 文件哈希
+   */
+  private getFileHash(filePath: string): string | null {
+    try {
+      if (!existsSync(filePath)) return null
+      const content = readFileSync(filePath, 'utf-8')
+      // 跳过空内容（可能是其他进程写入时的 truncate 中间状态）
+      if (content.length === 0) return null
+      return createHash('md5').update(content).digest('hex')
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * 更新文件哈希缓存，只有当文件内容发生变化时才更新并返回 true
+   *
+   * @param filePath 文件路径
+   * @returns 是否发生变化
+   */
+  updateFileHash(filePath: string): boolean {
+    const current = this.getFileHash(filePath)
+    if (!current) return false
+    const prev = this.fileHashes.get(filePath)
+    if (prev === current) return false
+    this.fileHashes.set(filePath, current)
+    return true
+  }
+
+  /**
+   * 检查指定名称的笔记目录是否已存在于缓存中
+   *
+   * @param name 笔记目录名称
+   * @returns 若存在则返回 true，否则返回 false
+   */
+  hasNoteDir(name: string) {
+    return this.noteDirCache.has(name)
+  }
+
+  /**
+   * 将指定名称的笔记目录添加到缓存中
+   *
+   * @param name 笔记目录名称
+   */
+  addNoteDir(name: string) {
+    this.noteDirCache.add(name)
+  }
+  /**
+   * 从缓存中移除指定名称的笔记目录
+   *
+   * @param name 笔记目录名称
+   */
+  deleteNoteDir(name: string) {
+    this.noteDirCache.delete(name)
+  }
+
+  /**
+   * 清空所有缓存数据，包括文件哈希、笔记目录和配置快照
+   */
+  clearAll(): void {
+    this.fileHashes.clear()
+    this.noteDirCache.clear()
+    this.configCache.clear()
+  }
+
+  /**
+   * 清除指定笔记目录相关的缓存数据，包括 README.md 和 .tnotes.json 的文件哈希及配置快照
+   *
+   * @param noteDirName 笔记目录名称
+   */
+  clearNoteCaches(noteDirName: string): void {
+    const readmePath = join(this.config.notesDir, noteDirName, 'README.md')
+    const configPath = join(this.config.notesDir, noteDirName, '.tnotes.json')
+    this.fileHashes.delete(readmePath)
+    this.fileHashes.delete(configPath)
+    this.configCache.delete(configPath)
+  }
+
+  /**
+   * 获取指定配置文件路径对应的配置快照
+   *
+   * @param configPath 配置文件路径（通常为 .tnotes.json 的绝对路径）
+   * @returns 配置快照，若不存在则返回 undefined
+   */
+  getConfigSnapshot(configPath: string): ConfigSnapshot | undefined {
+    return this.configCache.get(configPath)
+  }
+
+  /**
+   * 设置指定配置文件路径的配置快照到缓存中
+   *
+   * @param configPath 配置文件路径（通常为 .tnotes.json 的绝对路径）
+   * @param snapshot 配置快照对象
+   */
+  setConfigSnapshot(configPath: string, snapshot: ConfigSnapshot): void {
+    this.configCache.set(configPath, snapshot)
+  }
+
+  /**
+   * 读取指定配置文件的快照
+   *
+   * 解析 .tnotes.json 配置文件，提取 done、enableDiscussions、description 字段。
+   *
+   * @param configPath 配置文件路径（通常为 .tnotes.json 的绝对路径）
+   * @returns 配置快照，若文件不存在或解析失败则返回 null
+   */
+  readConfigSnapshot(configPath: string): ConfigSnapshot | null {
+    try {
+      if (!existsSync(configPath)) return null
+      const content = readFileSync(configPath, 'utf-8')
+      const config = JSON.parse(content) as Partial<NoteConfig>
+      return {
+        done: Boolean(config.done),
+        enableDiscussions: Boolean(config.enableDiscussions),
+        description: config.description || '',
+      }
+    } catch (error) {
+      this.config.logger.error(`[读取配置快照] ${error}`)
+      return null
+    }
+  }
+
+  /**
+   * 从磁盘初始化监听状态缓存：
+   * 遍历笔记根目录下的所有子目录，将每个笔记目录的 README.md 和 .tnotes.json
+   * 的哈希值及配置快照加载到缓存中。
+   */
+  initializeFromDisk(): void {
+    try {
+      const noteDirs = readdirSync(this.config.notesDir)
+      this.clearAll()
+
+      for (const noteDir of noteDirs) {
+        const noteDirPath = join(this.config.notesDir, noteDir)
+        if (!statSync(noteDirPath).isDirectory()) continue
+
+        this.noteDirCache.add(noteDir)
+
+        const readmePath = join(noteDirPath, 'README.md')
+        const readmeHash = this.getFileHash(readmePath)
+        if (readmeHash) this.fileHashes.set(readmePath, readmeHash)
+
+        const configPath = join(noteDirPath, '.tnotes.json')
+        const configHash = this.getFileHash(configPath)
+        if (configHash) {
+          this.fileHashes.set(configPath, configHash)
+          const snapshot = this.readConfigSnapshot(configPath)
+          if (snapshot) this.configCache.set(configPath, snapshot)
+        }
+      }
+    } catch (error) {
+      this.config.logger.warn(
+        `[initializeFromDisk] 初始化监听状态失败: ${error}`,
+      )
+    }
+  }
+}

package/services/git/index.ts

@@ -0,0 +1,7 @@
+/**
+ * services/git-service/index.ts
+ *
+ * Git 服务入口 - 导出 GitService 类
+ */
+
+export { GitService } from './service'