@tnotesjs/core 0.6.1 → 0.8.0

package/commands/models.ts

@@ -0,0 +1,87 @@
+/**
+ * commands/models.ts
+ *
+ * commands 层对外暴露的类型和常量
+ * 注意：此文件不应导入任何命令类，以避免循环引用
+ */
+
+/**
+ * TNotes 内置命令名称常量
+ */
+export const COMMAND_NAMES = {
+  BUILD: 'build',
+  CREATE_NOTES: 'create-notes',
+  DEV: 'dev',
+  HELP: 'help',
+  PREVIEW: 'preview',
+  PULL: 'pull',
+  PUSH: 'push',
+  RENAME_NOTE: 'rename-note',
+  INIT_SUB_REPO: 'init-sub-repo',
+  UPDATE: 'update',
+  UPDATE_COMPLETED_COUNT: 'update-completed-count',
+  UPDATE_NOTE_CONFIG: 'update-note-config',
+} as const
+
+/**
+ * TNotes 内置命令名称类型
+ */
+export type CommandName = (typeof COMMAND_NAMES)[keyof typeof COMMAND_NAMES]
+
+/**
+ * 命令描述映射（静态配置，无需实例化即可读取）
+ */
+export const COMMAND_DESCRIPTIONS: Record<CommandName, string> = {
+  [COMMAND_NAMES.DEV]: '启动知识库开发服务',
+  [COMMAND_NAMES.BUILD]: '构建知识库',
+  [COMMAND_NAMES.PREVIEW]: '预览构建后的知识库',
+  [COMMAND_NAMES.INIT_SUB_REPO]: '初始化 TNotes 子知识库（一次性脚手架）',
+  [COMMAND_NAMES.UPDATE]: '根据笔记内容更新知识库',
+  [COMMAND_NAMES.UPDATE_COMPLETED_COUNT]:
+    '更新完成笔记数量历史记录（近 1 年，最近 12 个月）',
+  [COMMAND_NAMES.CREATE_NOTES]: '新建笔记（支持批量创建）',
+  [COMMAND_NAMES.PUSH]: '将知识库推送到 GitHub',
+  [COMMAND_NAMES.PULL]: '将 GitHub 的知识库拉下来',
+  [COMMAND_NAMES.UPDATE_NOTE_CONFIG]: '更新笔记配置文件',
+  [COMMAND_NAMES.RENAME_NOTE]: '重命名笔记',
+  [COMMAND_NAMES.HELP]: '显示帮助信息',
+}
+
+/**
+ * 命令参数选项常量
+ */
+export const COMMAND_OPTIONS = {
+  QUIET: 'quiet',
+  FORCE: 'force',
+} as const
+
+export type CommandOption =
+  (typeof COMMAND_OPTIONS)[keyof typeof COMMAND_OPTIONS]
+
+/**
+ * 命令选项类型（传递给 BaseCommand.setOptions 的参数类型）
+ */
+export interface CommandOptions {
+  force?: boolean
+  quiet?: boolean
+  [key: string]: unknown
+}
+
+/**
+ * 命令参数类型
+ */
+export type CommandArgs = {
+  [K in CommandName]?: boolean
+} & {
+  [COMMAND_OPTIONS.QUIET]?: boolean
+  [COMMAND_OPTIONS.FORCE]?: boolean
+}
+
+/**
+ * 命令接口
+ */
+export interface Command {
+  name: CommandName
+  description: string
+  execute(): Promise<void>
+}

package/commands/note/CreateNoteCommand.ts

@@ -0,0 +1,160 @@
+/**
+ * commands/note/CreateNoteCommand.ts
+ *
+ * 新建笔记命令 - 使用 NoteService（支持批量创建，生成全局唯一 ID）
+ */
+
+import { createInterface } from 'readline'
+import { v4 as uuidv4 } from 'uuid'
+
+import { NoteService, ReadmeService } from '../../services'
+import { BaseCommand } from '../BaseCommand'
+
+export class CreateNoteCommand extends BaseCommand {
+  private noteService: NoteService
+  private readmeService: ReadmeService
+
+  constructor() {
+    super('create-notes')
+    
+    this.noteService = NoteService.getInstance()
+    this.readmeService = ReadmeService.getInstance()
+  }
+
+  protected async run(): Promise<void> {
+    this.logger.info('创建新笔记...')
+
+    // 提示用户输入要创建的笔记数量
+    const count = await this.promptForCount()
+
+    // 批量创建笔记
+    let successCount = 0
+    let failCount = 0
+    const createdNotes: string[] = []
+
+    // 预先扫描一次，构建已使用编号集合，避免循环内重复扫描
+    const existingNotes = this.noteService.getAllNotes()
+    const usedIndexes = new Set<number>()
+    for (const note of existingNotes) {
+      const index = parseInt(note.index, 10)
+      if (!isNaN(index) && index >= 1 && index <= 9999) {
+        usedIndexes.add(index)
+      }
+    }
+
+    for (let i = 1; i <= count; i++) {
+      try {
+        // 为每篇笔记提示标题（如果是批量创建，使用默认标题）
+        let title: string
+        if (count === 1) {
+          title = await this.promptForTitle()
+        } else {
+          title = `new`
+          this.logger.info(`[${i}/${count}] 创建笔记: ${title}`)
+        }
+
+        // 生成全局唯一的 UUID 作为配置文件中的 id
+        const configId = uuidv4()
+
+        const note = await this.noteService.createNote({
+          title: title || `new`,
+          enableDiscussions: false,
+          configId, // 传递 UUID 作为配置 ID（跨知识库唯一）
+          usedIndexes, // 传入已使用编号集合，避免重复扫描
+        })
+
+        // 将新创建的笔记编号加入集合，确保后续创建不会冲突
+        const newIndex = parseInt(note.index, 10)
+        if (!isNaN(newIndex)) {
+          usedIndexes.add(newIndex)
+        }
+
+        createdNotes.push(note.dirName)
+        successCount++
+
+        if (count === 1) {
+          this.logger.success(`笔记创建成功: ${note.dirName}`)
+          this.logger.info(`笔记路径: ${note.path}`)
+          this.logger.info(`笔记编号: ${note.index}`)
+          this.logger.info(`配置ID: ${configId}`)
+        } else {
+          this.logger.success(`[${i}/${count}] 创建成功: ${note.dirName}`)
+        }
+      } catch (error) {
+        failCount++
+        this.logger.error(`[${i}/${count}] 创建失败`, error)
+      }
+    }
+
+    // 显示统计信息
+    if (count > 1) {
+      console.log('')
+      this.logger.info(
+        `📊 创建完成: 成功 ${successCount} 篇, 失败 ${failCount} 篇`,
+      )
+    }
+
+    // 自动更新索引文件（TOC.md、sidebar.json）
+    if (successCount > 0) {
+      this.logger.info('正在更新知识库索引...')
+      await this.readmeService.updateAllReadmes()
+      this.logger.success('知识库索引更新完成')
+    }
+  }
+
+  /**
+   * 提示用户输入要创建的笔记数量
+   */
+  private async promptForCount(): Promise<number> {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    })
+
+    return new Promise((resolve) => {
+      rl.question('\n📝 请输入要创建的笔记数量（默认为 1）: ', (answer) => {
+        rl.close()
+
+        // 解析输入
+        const trimmed = answer.trim()
+
+        // 如果输入为空，默认为 1
+        if (!trimmed) {
+          this.logger.info('使用默认数量: 1')
+          resolve(1)
+          return
+        }
+
+        // 尝试解析为数字
+        const num = parseInt(trimmed, 10)
+
+        // 如果不是正整数，视为 1
+        if (isNaN(num) || num < 1 || !Number.isInteger(num)) {
+          this.logger.warn(`输入 "${trimmed}" 不是有效的正整数，使用默认值: 1`)
+          resolve(1)
+          return
+        }
+
+        this.logger.info(`将创建 ${num} 篇笔记`)
+        resolve(num)
+      })
+    })
+  }
+
+  /**
+   * 提示用户输入笔记标题
+   */
+  private async promptForTitle(): Promise<string> {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    })
+
+    return new Promise((resolve) => {
+      rl.question('请输入笔记标题: ', (answer) => {
+        rl.close()
+        resolve(answer.trim())
+      })
+    })
+  }
+}

package/commands/note/RenameNoteCommand.ts

@@ -0,0 +1,147 @@
+/**
+ * commands/note/RenameNoteCommand.ts
+ *
+ * 重命名笔记命令 - 用于在开发环境中重命名笔记文件夹
+ */
+
+import { existsSync, renameSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+
+import { NOTES_PATH, REPO_NOTES_URL } from '../../config/constants'
+import { ROOT_DIR_PATH } from '../../config/constants'
+import { generateNoteTitle } from '../../config/templates'
+import { NoteService, FileWatcherService } from '../../services'
+import { reconcileTocFromFiles } from '../../services/reconcileToc'
+import { validateNoteTitle } from '../../utils'
+import { BaseCommand } from '../BaseCommand'
+
+interface RenameNoteParams {
+  noteIndex: string
+  newTitle: string
+}
+
+export class RenameNoteCommand extends BaseCommand {
+  private noteService: NoteService
+
+  constructor() {
+    super('rename-note')
+    this.noteService = NoteService.getInstance()
+  }
+
+  protected async run(): Promise<void> {
+    // 从命令行参数读取
+    const noteIndex = process.env.NOTE_ID
+    const newTitle = process.env.NOTE_TITLE
+
+    if (!noteIndex || !newTitle) {
+      throw new Error('缺少 NOTE_ID 或 NOTE_TITLE 参数')
+    }
+
+    try {
+      await this.renameNote({ noteIndex, newTitle })
+      this.logger.success(`笔记 ${noteIndex} 已重命名为: ${newTitle}`)
+    } catch (error) {
+      this.logger.error('重命名失败', error)
+      throw error
+    }
+  }
+
+  /**
+   * 重命名笔记（可被外部调用）
+   */
+  async renameNote(params: RenameNoteParams): Promise<void> {
+    const { noteIndex, newTitle } = params
+
+    // 验证笔记是否存在
+    const note = this.noteService.getNoteByIndex(noteIndex)
+    if (!note) {
+      throw new Error(`笔记未找到: ${noteIndex}`)
+    }
+
+    // 验证新标题
+    const validation = validateNoteTitle(newTitle)
+    if (!validation.valid) {
+      throw new Error(validation.error || '标题格式无效')
+    }
+
+    // 构建新的文件夹名称
+    const newDirName = `${noteIndex}. ${newTitle.trim()}`
+    const newPath = join(NOTES_PATH, newDirName)
+
+    // 检查新路径是否已存在
+    if (existsSync(newPath)) {
+      throw new Error(`目标文件夹已存在: ${newDirName}`)
+    }
+
+    // 重命名文件夹
+    // Windows 上 fs.watch 会锁住文件夹句柄，需要先挂起监听
+    const watcher = FileWatcherService.getInstance()
+    try {
+      if (watcher) watcher.suspend()
+      renameSync(note.path, newPath)
+      this.logger.info(`✅ 文件夹已重命名:`)
+      this.logger.info(`  原名称: ${note.dirName}`)
+      this.logger.info(`  新名称: ${newDirName}`)
+    } catch (error) {
+      throw new Error(
+        `重命名文件夹失败: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      )
+    } finally {
+      if (watcher) watcher.unsuspend()
+    }
+
+    // 更新笔记内部的标题（README.md 第一行）
+    try {
+      this.logger.info('正在更新笔记内部标题...')
+      const readmePath = join(newPath, 'README.md')
+
+      if (existsSync(readmePath)) {
+        const content = readFileSync(readmePath, 'utf-8')
+        const lines = content.split('\n')
+
+        // 查找第一个一级标题
+        let h1Index = -1
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].trim().startsWith('# ')) {
+            h1Index = i
+            break
+          }
+        }
+
+        if (h1Index !== -1) {
+          // 生成新的标题
+          const newH1 = generateNoteTitle(
+            noteIndex,
+            newTitle.trim(),
+            REPO_NOTES_URL,
+          )
+          lines[h1Index] = newH1
+
+          // 写回文件
+          writeFileSync(readmePath, lines.join('\n'), 'utf-8')
+          this.logger.success('✅ 笔记标题已更新')
+        } else {
+          this.logger.warn(
+            `⚠️  笔记标题格式不符合规范，未找到一级标题，请手动检查修正: ${readmePath}`,
+          )
+        }
+      }
+    } catch (error) {
+      this.logger.warn('⚠️  更新笔记标题时出错:', error)
+    }
+
+    // 重命名成功后，更新 TOC.md 和 sidebar.json
+    try {
+      this.logger.info('正在更新 TOC.md 和 sidebar.json...')
+
+      await reconcileTocFromFiles(ROOT_DIR_PATH)
+
+      this.logger.success('✅ 全局文件已更新')
+    } catch (error) {
+      this.logger.warn('⚠️  文件夹重命名成功,但更新全局文件时出错:', error)
+      // 不抛出错误,因为主要任务(重命名)已完成
+    }
+  }
+}

package/commands/note/UpdateNoteConfigCommand.ts

@@ -0,0 +1,78 @@
+/**
+ * commands/note/UpdateNoteConfigCommand.ts
+ *
+ * 更新笔记配置命令 - 用于在开发环境中更新笔记配置
+ */
+
+import { NoteService } from '../../services'
+import { BaseCommand } from '../BaseCommand'
+
+import type { NoteConfig } from '../../types'
+
+interface UpdateConfigParams {
+  noteIndex: string
+  config: Partial<
+    Pick<NoteConfig, 'done' | 'enableDiscussions' | 'description'>
+  >
+}
+
+export class UpdateNoteConfigCommand extends BaseCommand {
+  private noteService: NoteService
+
+  constructor() {
+    super('update-note-config')
+    this.noteService = NoteService.getInstance()
+  }
+
+  protected async run(): Promise<void> {
+    // 从命令行参数读取配置（用于 CLI 调用）
+    const noteIndex = process.env.NOTE_ID
+    const done = process.env.NOTE_DONE === 'true'
+    const enableDiscussions = process.env.NOTE_DISCUSSIONS === 'true'
+    const description = process.env.NOTE_DESCRIPTION || ''
+
+    if (!noteIndex) {
+      throw new Error('缺少 NOTE_ID 参数')
+    }
+
+    try {
+      await this.updateConfig({
+        noteIndex,
+        config: {
+          done,
+          enableDiscussions,
+          description,
+        },
+      })
+
+      this.logger.success(`笔记 ${noteIndex} 配置已更新`)
+    } catch (error) {
+      this.logger.error('更新配置失败', error)
+      throw error
+    }
+  }
+
+  /**
+   * 更新笔记配置（可被外部调用）
+   */
+  async updateConfig(params: UpdateConfigParams): Promise<void> {
+    const { noteIndex, config } = params
+
+    // 验证笔记是否存在
+    const note = this.noteService.getNoteByIndex(noteIndex)
+    if (!note) {
+      throw new Error(`笔记未找到: ${noteIndex}`)
+    }
+
+    // 更新配置
+    await this.noteService.updateNoteConfig(noteIndex, config)
+
+    this.logger.info(`✅ 笔记 ${noteIndex} 配置已更新:`)
+    if (config.done !== undefined)
+      this.logger.info(`  - 完成状态: ${config.done}`)
+    if (config.enableDiscussions !== undefined)
+      this.logger.info(`  - 评论状态: ${config.enableDiscussions}`)
+    if (config.description !== undefined)
+      this.logger.info(`  - 笔记简介: ${config.description || '(空)'}`)
+  }
+}

package/commands/note/index.ts

@@ -0,0 +1,9 @@
+/**
+ * commands/note/index.ts
+ *
+ * Note 命令统一导出
+ */
+
+export { CreateNoteCommand } from './CreateNoteCommand'
+export { UpdateNoteConfigCommand } from './UpdateNoteConfigCommand'
+export { RenameNoteCommand } from './RenameNoteCommand'

package/commands/registry.ts

@@ -0,0 +1,47 @@
+/**
+ * commands/registry.ts
+ *
+ * 命令注册表 - 管理命令的注册、实例化和获取
+ */
+
+import { BuildCommand, PreviewCommand } from './build'
+import { DevCommand } from './dev'
+import { PushCommand, PullCommand } from './git'
+import { InitSubRepoCommand } from './init-sub-repo'
+import { HelpCommand } from './misc'
+import { type Command, type CommandName } from './models'
+import {
+  CreateNoteCommand,
+  UpdateNoteConfigCommand,
+  RenameNoteCommand,
+} from './note'
+import { UpdateCommand } from './update'
+import { UpdateCompletedCountCommand } from './update-completed-count'
+
+/** 命令注册表（懒加载） */
+const commandFactories: Record<CommandName, () => Command> = {
+  'build': () => new BuildCommand(),
+  'create-notes': () => new CreateNoteCommand(),
+  'dev': () => new DevCommand(),
+  'init-sub-repo': () => new InitSubRepoCommand(),
+  'help': () => new HelpCommand(),
+  'preview': () => new PreviewCommand(),
+  'pull': () => new PullCommand(),
+  'push': () => new PushCommand(),
+  'rename-note': () => new RenameNoteCommand(),
+  'update-completed-count': () => new UpdateCompletedCountCommand(),
+  'update-note-config': () => new UpdateNoteConfigCommand(),
+  'update': () => new UpdateCommand(),
+}
+
+/** 命令实例缓存 */
+const commandCache = new Map<CommandName, Command>()
+
+/** 获取命令（懒加载，首次调用时才实例化） */
+export function getCommand(name: CommandName): Command | undefined {
+  if (!commandFactories[name]) return undefined
+
+  if (!commandCache.has(name)) commandCache.set(name, commandFactories[name]())
+
+  return commandCache.get(name)
+}