@tnotesjs/core 0.7.0 → 0.8.0

package/commands/BaseCommand.ts

@@ -0,0 +1,58 @@
+/**
+ * commands/BaseCommand.ts
+ *
+ * 命令基类
+ */
+
+import { COMMAND_DESCRIPTIONS } from './models'
+import { handleError, logger } from '../utils'
+
+import type { Command, CommandName, CommandOptions } from './models'
+import type { Logger } from '../utils'
+
+
+/**
+ * 命令基类
+ */
+export abstract class BaseCommand implements Command {
+  protected logger: Logger
+  protected options: CommandOptions = {}
+
+  /** 命令描述（从静态配置读取） */
+  get description(): string {
+    return COMMAND_DESCRIPTIONS[this.name]
+  }
+
+  constructor(public name: CommandName) {
+    this.logger = logger.child(name)
+  }
+
+  /**
+   * 设置命令选项
+   */
+  setOptions(options: CommandOptions): void {
+    this.options = { ...this.options, ...options }
+  }
+
+  /**
+   * 执行命令（带错误处理）
+   */
+  async execute(): Promise<void> {
+    const startTime = Date.now()
+
+    try {
+      this.logger.start(this.description)
+      await this.run()
+      const duration = Date.now() - startTime
+      this.logger.done(`命令执行耗时：${duration} ms`)
+    } catch (error) {
+      handleError(error)
+      throw error
+    }
+  }
+
+  /**
+   * 子类需要实现的运行逻辑
+   */
+  protected abstract run(): Promise<void>
+}

package/commands/build/BuildCommand.ts

@@ -0,0 +1,25 @@
+/**
+ * commands/build/BuildCommand.ts
+ *
+ * 构建命令 - 使用 VitepressService
+ */
+
+import { VitepressService } from '../../services'
+import { BaseCommand } from '../BaseCommand'
+
+export class BuildCommand extends BaseCommand {
+  private vitepressService: VitepressService
+
+  constructor() {
+    super('build')
+    this.vitepressService = new VitepressService()
+  }
+
+  protected async run(): Promise<void> {
+    this.logger.info('开始构建知识库...')
+
+    await this.vitepressService.build()
+
+    this.logger.success('知识库构建完成')
+  }
+}

package/commands/build/PreviewCommand.ts

@@ -0,0 +1,29 @@
+/**
+ * commands/build/PreviewCommand.ts
+ *
+ * 预览命令 - 使用 VitepressService
+ */
+
+import { VitepressService } from '../../services'
+import { BaseCommand } from '../BaseCommand'
+
+export class PreviewCommand extends BaseCommand {
+  private vitepressService: VitepressService
+
+  constructor() {
+    super('preview')
+    this.vitepressService = new VitepressService()
+  }
+
+  protected async run(): Promise<void> {
+    this.logger.info('启动预览服务器...')
+
+    const pid = await this.vitepressService.preview()
+
+    if (pid) {
+      this.logger.success(`预览服务器已启动 (PID: ${pid})`)
+    } else {
+      this.logger.error('启动预览服务器失败')
+    }
+  }
+}

package/commands/build/index.ts

@@ -0,0 +1,8 @@
+/**
+ * commands/build/index.ts
+ *
+ * Build 命令统一导出
+ */
+
+export { BuildCommand } from './BuildCommand'
+export { PreviewCommand } from './PreviewCommand'

package/commands/dev/DevCommand.ts

@@ -0,0 +1,75 @@
+/**
+ * commands/dev/DevCommand.ts
+ *
+ * 开发服务器命令 - 使用 VitepressService 和 FileWatcherService
+ */
+
+import { ConfigManager } from '../../config/ConfigManager'
+import { ROOT_DIR_PATH } from '../../config/constants'
+import { NoteManager, NoteIndexCache } from '../../core'
+import { VitepressService, FileWatcherService } from '../../services'
+import { reconcileTocFromFiles } from '../../services/reconcileToc'
+import { BaseCommand } from '../BaseCommand'
+
+export class DevCommand extends BaseCommand {
+  private configManager: ConfigManager
+  private fileWatcherService: FileWatcherService
+  private noteIndexCache: NoteIndexCache
+  private noteManager: NoteManager
+  private vitepressService: VitepressService
+
+  constructor() {
+    super('dev')
+    
+    this.configManager = ConfigManager.getInstance()
+    this.fileWatcherService = new FileWatcherService()
+    this.noteIndexCache = NoteIndexCache.getInstance()
+    this.noteManager = NoteManager.getInstance()
+    this.vitepressService = new VitepressService()
+  }
+
+  protected async run(): Promise<void> {
+    // 1. 扫描笔记目录并校验完整性（noteIndex 冲突 + config id 缺失/重复）
+    const notes = this.noteManager.scanNotes()
+    this.logger.info(`扫描到 ${notes.length} 篇笔记`)
+
+    // 2. 初始化笔记索引缓存（在 VitePress 启动前完成，供插件使用）
+    this.noteIndexCache.initialize(notes)
+
+    // 3. 重新生成 sidebar.json（必须在 VitePress 启动前完成，基于 TOC.md）
+    //
+    // sidebar.data.ts 这个 VitePress data loader 只在启动时读取磁盘上的
+    // sidebar.json，运行期间靠 HMR 监听其变化做热更新。但冷启动时若 sidebar.json
+    // 与当前笔记/TOC.md 不同步（例如 git pull、切分支、或上次会话外离线增删改了
+    // 笔记），VitePress 就会把过期数据读进来，导致侧边栏显示错误，需要手动删除
+    // .vitepress/cache 才能恢复。这里在启动前主动重建一次，消除启动时的过期窗口。
+    // files→TOC 对齐（Workspace）：冷启动前从磁盘真值重建 TOC/sidebar
+    await reconcileTocFromFiles(ROOT_DIR_PATH)
+
+    // 4. 启动 VitePress 服务器（会等待服务就绪后返回）
+    const result = await this.vitepressService.startServer()
+
+    if (result) {
+      const versionInfo = result.version ? `（v${result.version}）` : ''
+      this.logger.success(
+        `VitePress 服务${versionInfo}已就绪，耗时：${result.elapsed} ms`,
+      )
+
+      // 5. 启动文件监听服务
+      const watcherStart = Date.now()
+      this.fileWatcherService.start()
+      const watcherElapsed = Date.now() - watcherStart
+      this.logger.success(`文件监听服务已就绪，耗时：${watcherElapsed} ms`)
+
+      // 6. 显示本地开发服务地址
+      const port =
+        this.configManager.get('port') || VitepressService.DEFAULT_DEV_PORT
+      const repoName = this.configManager.get('repoName')
+      this.logger.info(
+        `本地开发服务地址：http://localhost:${port}/${repoName}/`,
+      )
+    } else {
+      this.logger.error('启动服务器失败')
+    }
+  }
+}

package/commands/dev/index.ts

@@ -0,0 +1,7 @@
+/**
+ * commands/dev/index.ts
+ *
+ * Dev 命令统一导出
+ */
+
+export { DevCommand } from './DevCommand'

package/commands/git/PullCommand.ts

@@ -0,0 +1,25 @@
+/**
+ * commands/git/PullCommand.ts
+ *
+ * Git Pull 命令 - 使用 GitService
+ */
+
+import { GitService } from '../../services'
+import { BaseCommand } from '../BaseCommand'
+
+export class PullCommand extends BaseCommand {
+  private gitService: GitService
+
+  constructor() {
+    super('pull')
+    this.gitService = new GitService()
+  }
+
+  protected async run(): Promise<void> {
+    this.logger.info('正在从远程仓库拉取...')
+
+    await this.gitService.pull()
+
+    this.logger.success('拉取完成')
+  }
+}

package/commands/git/PushCommand.ts

@@ -0,0 +1,64 @@
+/**
+ * commands/git/PushCommand.ts
+ *
+ * Git Push 命令
+ *
+ * 流程：git add -A → git commit → git push
+ */
+
+import { ROOT_DIR_PATH } from '../../config/constants'
+import { GitManager } from '../../core'
+import { GitService } from '../../services'
+import { runCommand } from '../../utils'
+import { BaseCommand } from '../BaseCommand'
+
+export class PushCommand extends BaseCommand {
+  private gitManager: GitManager
+  private gitService: GitService
+
+  constructor() {
+    super('push')
+
+    this.gitManager = new GitManager(ROOT_DIR_PATH)
+    this.gitService = new GitService()
+  }
+
+  protected async run(): Promise<void> {
+    try {
+      // 1. 检查是否有更改或已有未推送的提交
+      this.logger.info('检查是否有更改...')
+      const status = await this.gitManager.getStatus()
+      const hasPendingCommits = (status.ahead ?? 0) > 0
+
+      if (!status.hasChanges && !hasPendingCommits) {
+        this.logger.info('没有更改需要推送')
+        return
+      }
+
+      const force = this.options.force === true
+      if (force) {
+        this.logger.warn('使用强制推送模式 (--force)')
+      }
+
+      if (status.hasChanges) {
+        this.logger.info(
+          `检测到 ${status.files.length} 个变更文件，正在提交...`,
+        )
+        const commitMessage = this.gitService.generateCommitMessage()
+        await runCommand('git add -A', ROOT_DIR_PATH)
+        await runCommand(`git commit -m "${commitMessage}"`, ROOT_DIR_PATH)
+      } else {
+        this.logger.info(`检测到 ${status.ahead} 个未推送的提交，直接推送...`)
+      }
+
+      // 2. 推送到远程
+      this.logger.info('正在推送到远程仓库...')
+      const pushCmd = force ? 'git push --force' : 'git push'
+      await runCommand(pushCmd, ROOT_DIR_PATH)
+      this.logger.success('推送完成')
+    } catch (error) {
+      this.logger.error('推送失败:', error)
+      throw error
+    }
+  }
+}

package/commands/git/index.ts

@@ -0,0 +1,8 @@
+/**
+ * commands/git/index.ts
+ *
+ * Git 命令统一导出
+ */
+
+export { PushCommand } from './PushCommand'
+export { PullCommand } from './PullCommand'

package/commands/index.ts

@@ -0,0 +1,11 @@
+/**
+ * commands/index.ts
+ *
+ * commands entry（对外暴露的公共 API）
+ */
+
+export { UpdateCommand } from './update'
+export { PushCommand } from './git'
+export { COMMAND_NAMES } from './models'
+export type { CommandArgs } from './models'
+export { getCommand } from './registry'

package/commands/init-sub-repo/InitSubRepoCommand.ts

@@ -0,0 +1,206 @@
+/**
+ * commands/init-sub-repo/InitSubRepoCommand.ts
+ *
+ * 初始化 TNotes 子知识库
+ */
+
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { createInterface } from 'readline'
+import { fileURLToPath } from 'url'
+import { v4 as uuidv4 } from 'uuid'
+
+import { getConfigManager } from '../../config/ConfigManager'
+import { ROOT_DIR_PATH } from '../../config/constants'
+import {
+  buildInitContext,
+  buildManualSteps,
+  defaultDisplayName,
+  DEFAULT_DESCRIPTION,
+  DEFAULT_PORT,
+  getInitializedConfigPath,
+  isAlreadyInitialized,
+  validatePort,
+  validateTopic,
+  InitSubRepoService,
+} from '../../services/init-sub-repo'
+import { reconcileTocFromFiles } from '../../services/reconcileToc'
+import { BaseCommand } from '../BaseCommand'
+
+import type { InitSubRepoInput } from '../../services/init-sub-repo'
+
+function readCoreVersion(): string {
+  const moduleDir = dirname(fileURLToPath(import.meta.url))
+  let dir = moduleDir
+  while (dir !== dirname(dir)) {
+    const pkgPath = join(dir, 'package.json')
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as {
+        name?: string
+        version?: string
+      }
+      if (pkg.name === '@tnotesjs/core' && pkg.version) return pkg.version
+    } catch {
+      // continue walking up
+    }
+    dir = dirname(dir)
+  }
+  return '0.1.28'
+}
+
+export class InitSubRepoCommand extends BaseCommand {
+  private rootPath: string
+
+  constructor() {
+    super('init-sub-repo')
+    this.rootPath = process.cwd()
+  }
+
+  protected async run(): Promise<void> {
+    if (isAlreadyInitialized(this.rootPath)) {
+      const configPath = getInitializedConfigPath(this.rootPath)
+      this.logger.info(
+        `检测到 .tnotes.json 配置文件：${configPath}，当前仓库已经是一个 TNotes 知识库`,
+      )
+      return
+    }
+
+    this.logger.info('初始化 TNotes 子知识库')
+    this.logger.info('')
+
+    const input = await this.promptForInput()
+    const ctx = buildInitContext(input)
+
+    this.logger.info('')
+    this.logger.info('即将创建以下知识库：')
+    this.logger.info(`  仓库名：${ctx.repoName}`)
+    this.logger.info(`  展示名：${ctx.displayName}`)
+    this.logger.info(`  端口：${ctx.port}`)
+    this.logger.info(`  描述：${ctx.description}`)
+    this.logger.info('')
+
+    const confirmed = await this.promptConfirm('确认初始化？ [Y/n] ')
+    if (!confirmed) {
+      this.logger.info('已取消初始化')
+      return
+    }
+
+    const service = InitSubRepoService.fromModuleUrl(import.meta.url, this.rootPath)
+    const result = service.writeScaffold(input)
+
+    if (result.created.length > 0) {
+      this.logger.success(`已创建 ${result.created.length} 个文件：`)
+      for (const file of result.created) {
+        this.logger.info(`  + ${file}`)
+      }
+    }
+
+    if (result.updated.length > 0) {
+      this.logger.success(`已更新 ${result.updated.length} 个文件：`)
+      for (const file of result.updated) {
+        this.logger.info(`  ~ ${file}`)
+      }
+    }
+
+    if (result.skipped.length > 0) {
+      this.logger.warn(`已跳过 ${result.skipped.length} 个已存在文件：`)
+      for (const file of result.skipped) {
+        this.logger.info(`  - ${file}`)
+      }
+    }
+
+    getConfigManager().clearCache()
+
+    try {
+      this.logger.info('')
+      this.logger.info('正在规范化 TOC.md 并生成 sidebar.json...')
+      await reconcileTocFromFiles(ROOT_DIR_PATH)
+      this.logger.success('sidebar.json 已生成')
+    } catch (error) {
+      this.logger.warn(
+        `自动 update 失败（可稍后手动执行 pnpm tn:update）：${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      )
+    }
+
+    this.logger.info('')
+    this.logger.success('子知识库初始化完成！')
+    this.logger.info('')
+    this.logger.info('请手动完成以下步骤：')
+    for (const [index, step] of buildManualSteps(ctx).entries()) {
+      this.logger.info(`  ${index + 1}. ${step}`)
+    }
+  }
+
+  private async promptForInput(): Promise<InitSubRepoInput> {
+    const topic = await this.promptTopic()
+    const displayName = await this.promptDisplayName(topic)
+    const port = await this.promptPort()
+    const description = await this.promptDescription()
+
+    return {
+      topic,
+      displayName,
+      port,
+      description,
+      repoUuid: uuidv4(),
+      noteUuid: uuidv4(),
+      coreVersion: readCoreVersion(),
+    }
+  }
+
+  private async promptTopic(): Promise<string> {
+    while (true) {
+      const answer = await this.ask('请输入 topic（如 react，将生成 TNotes.react）: ')
+      const error = validateTopic(answer)
+      if (error) {
+        this.logger.warn(error)
+        continue
+      }
+      return answer.trim()
+    }
+  }
+
+  private async promptDisplayName(topic: string): Promise<string> {
+    const fallback = defaultDisplayName(topic)
+    const answer = await this.ask(
+      `请输入展示名（用于首页 hero，默认 ${fallback}）: `,
+    )
+    return answer.trim() || fallback
+  }
+
+  private async promptPort(): Promise<number> {
+    const answer = await this.ask(`请输入 dev 端口（默认 ${DEFAULT_PORT}）: `)
+    const { port, error } = validatePort(answer)
+    if (error) this.logger.warn(error)
+    return port
+  }
+
+  private async promptDescription(): Promise<string> {
+    const answer = await this.ask(
+      `请输入仓库描述（默认：${DEFAULT_DESCRIPTION}）: `,
+    )
+    return answer.trim() || DEFAULT_DESCRIPTION
+  }
+
+  private async promptConfirm(question: string): Promise<boolean> {
+    const answer = await this.ask(question)
+    const normalized = answer.trim().toLowerCase()
+    return normalized === '' || normalized === 'y' || normalized === 'yes'
+  }
+
+  private ask(question: string): Promise<string> {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    })
+
+    return new Promise((resolve) => {
+      rl.question(question, (answer) => {
+        rl.close()
+        resolve(answer)
+      })
+    })
+  }
+}

package/commands/init-sub-repo/index.ts

@@ -0,0 +1 @@
+export { InitSubRepoCommand } from './InitSubRepoCommand'

package/commands/misc/HelpCommand.ts

@@ -0,0 +1,104 @@
+/**
+ * commands/misc/HelpCommand.ts
+ *
+ * 帮助命令
+ */
+
+import { createLogger, LogLevel } from '../../utils'
+import { BaseCommand } from '../BaseCommand'
+import {
+  COMMAND_NAMES,
+  COMMAND_OPTIONS,
+  COMMAND_DESCRIPTIONS,
+} from '../models'
+
+import type { CommandOption } from '../models'
+
+/**
+ * 命令分组（用于帮助信息展示）
+ *
+ * 注意：`update-note-config` 和 `rename-note` 是内部命令，
+ * 由 VitePress dev server 通过 HTTP API 调用，不在 CLI 帮助中展示。
+ */
+const COMMAND_CATEGORIES = {
+  开发和构建: [COMMAND_NAMES.DEV, COMMAND_NAMES.BUILD, COMMAND_NAMES.PREVIEW],
+  内容管理: [
+    COMMAND_NAMES.UPDATE,
+    COMMAND_NAMES.UPDATE_COMPLETED_COUNT,
+    COMMAND_NAMES.CREATE_NOTES,
+  ],
+  'Git 操作': [COMMAND_NAMES.PUSH, COMMAND_NAMES.PULL],
+  初始化: [COMMAND_NAMES.INIT_SUB_REPO],
+  其他: [COMMAND_NAMES.HELP],
+} as const
+
+/** 命令选项描述（用于帮助信息展示） */
+const COMMAND_OPTIONS_INFO: Record<
+  CommandOption,
+  { description: string; applicableTo: string }
+> = {
+  [COMMAND_OPTIONS.QUIET]: {
+    description: '静默模式',
+    applicableTo: 'update',
+  },
+  [COMMAND_OPTIONS.FORCE]: {
+    description: '强制推送',
+    applicableTo: 'push',
+  },
+}
+
+export class HelpCommand extends BaseCommand {
+  constructor() {
+    super('help')
+
+    // 禁用时间戳输出，help 结束后其他命令不受影响
+    this.logger = createLogger('help', {
+      timestamp: false,
+      level: process.env.DEBUG ? LogLevel.DEBUG : LogLevel.INFO,
+    })
+  }
+
+  protected async run(): Promise<void> {
+    this.logger.info('TNotes 命令行工具')
+    this.logger.info('')
+    this.logger.info('用法：pnpm tn:<command> # 推荐')
+    this.logger.info('或者：npx tsx ./.vitepress/tnotes/index.ts --<command>')
+    this.logger.info('')
+    this.logger.info('可用命令：')
+    this.logger.info('')
+
+    for (const [category, cmdNames] of Object.entries(COMMAND_CATEGORIES)) {
+      this.logger.info(`  ${category}:`)
+      for (const cmdName of cmdNames) {
+        const description = COMMAND_DESCRIPTIONS[cmdName]
+        const paddingLength = Math.max(25 - cmdName.length, 1)
+        const padding = ' '.repeat(paddingLength)
+        this.logger.info(`    --${cmdName}${padding}${description}`)
+      }
+      this.logger.info('')
+    }
+
+    this.logger.info('示例：')
+    this.logger.info('  npx tsx ./.vitepress/tnotes/index.ts --dev')
+    this.logger.info('  pnpm tn:build')
+    this.logger.info('  pnpm tn:create-notes     # 批量创建笔记')
+    this.logger.info('  pnpm tn:update')
+    this.logger.info(
+      '  pnpm tn:update-completed-count           # 生成当前知识库最近 12 个月的完成笔记数量统计',
+    )
+    this.logger.info('')
+    this.logger.info('参数：')
+    for (const [option, info] of Object.entries(COMMAND_OPTIONS_INFO)) {
+      const paddingLength = Math.max(13 - option.length, 1)
+      const padding = ' '.repeat(paddingLength)
+      this.logger.info(
+        `  --${option}${padding}${info.description} (适用于 ${info.applicableTo})`,
+      )
+    }
+    this.logger.info('')
+    this.logger.info('环境变量：')
+    this.logger.info('  DEBUG=1        启用调试模式，显示详细日志')
+    this.logger.info('')
+    this.logger.info('更多信息请查看: .vitepress/tnotes/README.md')
+  }
+}

package/commands/misc/index.ts

@@ -0,0 +1,7 @@
+/**
+ * commands/misc/index.ts
+ *
+ * 其他杂项命令
+ */
+
+export { HelpCommand } from './HelpCommand'