@tnotesjs/core 0.2.1 → 0.2.2

package/services/git/service.ts

@@ -0,0 +1,114 @@
+/**
+ * services/git-service/service.ts
+ *
+ * Git 服务 - 封装 Git 操作相关的业务逻辑
+ */
+
+import { ROOT_DIR_PATH } from '../../config/constants'
+import { GitManager } from '../../core'
+import { logger } from '../../utils'
+
+/**
+ * Git 推送选项
+ */
+interface PushOptions {
+  message?: string
+  branch?: string
+  force?: boolean
+}
+
+/**
+ * Git 拉取选项
+ */
+interface PullOptions {
+  branch?: string
+  rebase?: boolean
+}
+
+/**
+ * Git 服务类
+ */
+export class GitService {
+  private gitManager: GitManager
+
+  constructor() {
+    this.gitManager = new GitManager(ROOT_DIR_PATH)
+  }
+
+  /**
+   * 推送到远程仓库
+   * @param options - 推送选项
+   */
+  async push(options: PushOptions = {}): Promise<void> {
+    const { message, branch, force = false } = options
+
+    logger.info('Pushing to remote repository...')
+
+    if (message) {
+      await this.gitManager.pushWithCommit(message, { force })
+    } else {
+      await this.gitManager.push({ setUpstream: !!branch, force })
+    }
+
+    logger.info('Push completed successfully')
+  }
+
+  /**
+   * 从远程仓库拉取
+   * @param options - 拉取选项
+   */
+  async pull(options: PullOptions = {}): Promise<void> {
+    const { rebase = false } = options
+
+    logger.info('Pulling from remote repository...')
+
+    await this.gitManager.pull({ rebase })
+
+    logger.info('Pull completed successfully')
+  }
+
+  /**
+   * 同步本地和远程仓库（先拉取后推送）
+   * @param commitMessage - 可选的提交信息
+   */
+  async sync(commitMessage?: string): Promise<void> {
+    logger.info('Syncing with remote repository...')
+
+    await this.gitManager.sync({ commitMessage })
+
+    logger.info('Sync completed successfully')
+  }
+
+  /**
+   * 检查是否有未提交的更改
+   * @returns 是否有未提交的更改
+   */
+  async hasChanges(): Promise<boolean> {
+    const status = await this.gitManager.getStatus()
+    return status.hasChanges
+  }
+
+  /**
+   * 生成自动提交信息
+   * @returns 自动生成的提交信息
+   */
+  generateCommitMessage(): string {
+    const date = new Date().toISOString().split('T')[0]
+    const time = new Date().toTimeString().split(' ')[0]
+    return `📝 Update notes - ${date} ${time}`
+  }
+
+  /**
+   * 快速提交并推送（使用自动生成的提交信息）
+   * @param options - 推送选项
+   */
+  async quickPush(options: { force?: boolean; skipCheck?: boolean } = {}): Promise<void> {
+    if (!options.skipCheck && !(await this.hasChanges())) {
+      logger.info('No changes to commit')
+      return
+    }
+
+    const message = this.generateCommitMessage()
+    await this.push({ message, force: options.force })
+  }
+}

package/services/index.ts

@@ -0,0 +1,15 @@
+/**
+ * services/index.ts
+ *
+ * Services 层统一 IO 层
+ */
+
+export { FileWatcherService } from './file-watcher'
+export { GitService } from './git'
+export { NoteService } from './note'
+export { ReadmeService } from './readme'
+export { TocService } from './toc'
+export { TimestampService } from './timestamp'
+export { VitepressService } from './vitepress'
+export { InitSubRepoService } from './init-sub-repo'
+export * from './init-sub-repo/initSubRepoLogic'

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

@@ -0,0 +1,2 @@
+export { InitSubRepoService, getCorePackageRoot, getTemplateRoot } from './service'
+export * from './initSubRepoLogic'

package/services/init-sub-repo/initSubRepoLogic.test.ts

@@ -0,0 +1,162 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { describe, expect, it, afterEach } from 'vitest'
+
+import {
+  buildInitContext,
+  buildRepoName,
+  buildPackageJsonTemplate,
+  defaultDisplayName,
+  isAlreadyInitialized,
+  mergePackageJson,
+  renderTocMd,
+  resolvePackageJsonMerge,
+  validatePort,
+  validateTopic,
+} from './initSubRepoLogic'
+import { InitSubRepoService } from './service'
+
+describe('initSubRepoLogic', () => {
+  const baseInput = {
+    topic: 'react',
+    displayName: 'React 笔记',
+    port: 8000,
+    description: '这是一个基于 tnotesjs/core 搭建的 TNotes 知识库。',
+    repoUuid: 'repo-uuid',
+    noteUuid: 'note-uuid',
+    coreVersion: '0.1.28',
+  }
+
+  it('buildRepoName 前缀 TNotes.', () => {
+    expect(buildRepoName('react')).toBe('TNotes.react')
+  })
+
+  it('defaultDisplayName 首字母大写', () => {
+    expect(defaultDisplayName('react')).toBe('React 笔记')
+  })
+
+  it('validateTopic 校验 slug', () => {
+    expect(validateTopic('react')).toBeNull()
+    expect(validateTopic('React')).not.toBeNull()
+    expect(validateTopic('')).not.toBeNull()
+    expect(validateTopic('1bad')).not.toBeNull()
+  })
+
+  it('validatePort 默认值与范围', () => {
+    expect(validatePort('')).toEqual({ port: 8000 })
+    expect(validatePort('9000')).toEqual({ port: 9000 })
+    expect(validatePort('abc').error).toBeTruthy()
+  })
+
+  it('renderTocMd 单行格式', () => {
+    const ctx = buildInitContext(baseInput)
+    expect(renderTocMd(ctx)).toBe('- [ ] 0001. TNotes.react\n')
+  })
+
+  it('mergePackageJson 保留额外字段', () => {
+    const template = buildPackageJsonTemplate('0.1.28')
+    const merged = mergePackageJson(
+      { name: 'my-repo', license: 'MIT', scripts: { old: 'x' } },
+      template,
+    )
+    expect(merged.name).toBe('my-repo')
+    expect(merged.license).toBe('MIT')
+    expect(merged.scripts).toEqual(template.scripts)
+    expect(merged.dependencies).toEqual(template.dependencies)
+  })
+
+  it('resolvePackageJsonMerge 新建与合并', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'init-sub-repo-'))
+    const pkgPath = join(dir, 'package.json')
+    const template = buildPackageJsonTemplate('0.1.28')
+
+    const created = resolvePackageJsonMerge(pkgPath, template)
+    expect(created.action).toBe('created')
+
+    writeFileSync(pkgPath, JSON.stringify({ name: 'keep-me' }), 'utf-8')
+    const updated = resolvePackageJsonMerge(pkgPath, template)
+    expect(updated.action).toBe('updated')
+    const parsed = JSON.parse(updated.content) as { name: string }
+    expect(parsed.name).toBe('keep-me')
+
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('isAlreadyInitialized 检测 .tnotes.json', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'init-sub-repo-'))
+    expect(isAlreadyInitialized(dir)).toBe(false)
+
+    writeFileSync(join(dir, '.tnotes.json'), '{}', 'utf-8')
+    expect(isAlreadyInitialized(dir)).toBe(true)
+
+    rmSync(dir, { recursive: true, force: true })
+  })
+})
+
+describe('InitSubRepoService', () => {
+  let tempRoot = ''
+  const templateRoot = join(process.cwd(), 'templates', 'sub-repo')
+
+  afterEach(() => {
+    if (tempRoot) {
+      rmSync(tempRoot, { recursive: true, force: true })
+      tempRoot = ''
+    }
+  })
+
+  it('writeScaffold 创建文件并跳过已存在项', () => {
+    tempRoot = mkdtempSync(join(tmpdir(), 'init-sub-repo-svc-'))
+    writeFileSync(join(tempRoot, 'README.md'), '# existing', 'utf-8')
+
+    const service = new InitSubRepoService(tempRoot, templateRoot)
+    const result = service.writeScaffold({
+      topic: 'demo',
+      displayName: 'Demo 笔记',
+      port: 8000,
+      description: 'desc',
+      repoUuid: 'repo-id',
+      noteUuid: 'note-id',
+      coreVersion: '0.1.28',
+    })
+
+    expect(result.created).toContain('.tnotes.json')
+    expect(result.created).toContain('TOC.md')
+    expect(result.skipped).toContain('README.md')
+    expect(existsSync(join(tempRoot, '.tnotes.json'))).toBe(true)
+
+    const config = JSON.parse(
+      readFileSync(join(tempRoot, '.tnotes.json'), 'utf-8'),
+    ) as { repoName: string; port: number }
+    expect(config.repoName).toBe('TNotes.demo')
+    expect(config.port).toBe(8000)
+  })
+
+  it('writeScaffold 合并已有 package.json', () => {
+    tempRoot = mkdtempSync(join(tmpdir(), 'init-sub-repo-svc-'))
+    writeFileSync(
+      join(tempRoot, 'package.json'),
+      JSON.stringify({ name: 'custom-name', private: true }),
+      'utf-8',
+    )
+
+    const service = new InitSubRepoService(tempRoot, templateRoot)
+    const result = service.writeScaffold({
+      topic: 'vue',
+      displayName: 'Vue 笔记',
+      port: 8100,
+      description: 'desc',
+      repoUuid: 'repo-id',
+      noteUuid: 'note-id',
+      coreVersion: '0.1.28',
+    })
+
+    expect(result.updated).toContain('package.json')
+    const pkg = JSON.parse(
+      readFileSync(join(tempRoot, 'package.json'), 'utf-8'),
+    ) as { name: string; private: boolean; scripts: Record<string, string> }
+    expect(pkg.name).toBe('custom-name')
+    expect(pkg.private).toBe(true)
+    expect(pkg.scripts['tn:dev']).toBe('tnotes --dev')
+  })
+})

package/services/init-sub-repo/initSubRepoLogic.ts

@@ -0,0 +1,304 @@
+/**
+ * services/init-sub-repo/initSubRepoLogic.ts
+ *
+ * 子知识库初始化纯函数（便于测试）
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join, resolve } from 'path'
+
+import { getDefaultConfig } from '../../config/defaultConfig'
+import {
+  generateNoteTitle,
+  getNewNoteReadmeBody,
+} from '../../config/templates'
+
+import type { NoteConfig, TNotesConfig } from '../../types'
+
+export const TOPIC_PATTERN = /^[a-z][a-z0-9-]*$/
+export const DEFAULT_PORT = 8000
+export const DEFAULT_DESCRIPTION =
+  '这是一个基于 tnotesjs/core 搭建的 TNotes 知识库。'
+export const GITHUB_ORG = 'tnotesjs'
+export const TNOTES_ROOT_URL = 'https://tnotesjs.github.io/TNotes'
+
+/** 静态模板文件（相对 templates/sub-repo/） */
+export const STATIC_TEMPLATE_FILES = [
+  '.github/workflows/deploy.yml',
+  '.vitepress/theme/index.ts',
+  '.vitepress/config.mts',
+  '.vitepress/env.d.ts',
+  '.vscode/settings.json',
+  '.vscode/tnotes.code-snippets',
+  'public/logo.png',
+  'public/favicon.ico',
+  '.gitattributes',
+  '.gitignore',
+  'tsconfig.json',
+] as const
+
+export interface InitSubRepoInput {
+  topic: string
+  displayName: string
+  port: number
+  description: string
+  repoUuid: string
+  noteUuid: string
+  coreVersion: string
+}
+
+export interface InitSubRepoContext extends InitSubRepoInput {
+  repoName: string
+  noteTitle: string
+  noteDirName: string
+}
+
+export interface PackageJsonTemplate {
+  type: 'module'
+  scripts: Record<string, string>
+  dependencies: Record<string, string>
+  devDependencies: Record<string, string>
+}
+
+export interface InitSubRepoWriteResult {
+  created: string[]
+  skipped: string[]
+  updated: string[]
+}
+
+export function buildRepoName(topic: string): string {
+  return `TNotes.${topic}`
+}
+
+export function defaultDisplayName(topic: string): string {
+  const label = topic.charAt(0).toUpperCase() + topic.slice(1)
+  return `${label} 笔记`
+}
+
+export function validateTopic(topic: string): string | null {
+  const trimmed = topic.trim()
+  if (!trimmed) return 'topic 不能为空'
+  if (!TOPIC_PATTERN.test(trimmed)) {
+    return 'topic 须以小写字母开头，仅含小写字母、数字、连字符'
+  }
+  return null
+}
+
+export function validatePort(raw: string): { port: number; error?: string } {
+  const trimmed = raw.trim()
+  if (!trimmed) return { port: DEFAULT_PORT }
+
+  const port = Number.parseInt(trimmed, 10)
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+    return { port: DEFAULT_PORT, error: '端口须为 1024–65535 之间的整数，已使用默认值 8000' }
+  }
+  return { port }
+}
+
+export function buildInitContext(input: InitSubRepoInput): InitSubRepoContext {
+  const repoName = buildRepoName(input.topic)
+  const noteTitle = repoName
+  const noteDirName = `0001. ${noteTitle}`
+
+  return {
+    ...input,
+    repoName,
+    noteTitle,
+    noteDirName,
+  }
+}
+
+export function buildTNotesConfig(ctx: InitSubRepoContext): TNotesConfig {
+  const config = getDefaultConfig(ctx.repoName)
+
+  config.id = ctx.repoUuid
+  config.port = ctx.port
+  config.root_item = {
+    ...config.root_item,
+    title: ctx.topic,
+    details: ctx.displayName,
+    link: `https://tnotesjs.github.io/${ctx.repoName}/`,
+  }
+  config.menuItems = [
+    { text: '🏠 Home', link: '/' },
+    { text: '⚙️ Settings', link: '/Settings' },
+    { text: '📒 TNotes', link: TNOTES_ROOT_URL },
+    {
+      text: '📂 TNotes.yuque',
+      link: 'https://www.yuque.com/tdahuyou/tnotes.yuque',
+    },
+  ]
+
+  return config
+}
+
+export function buildNoteConfig(noteUuid: string): NoteConfig {
+  return {
+    id: noteUuid,
+    bilibili: [],
+    tnotes: [],
+    yuque: [],
+    done: false,
+    enableDiscussions: false,
+    description: '',
+  }
+}
+
+export function buildRepoNotesUrl(repoName: string): string {
+  return `https://github.com/${GITHUB_ORG}/${repoName}/tree/main/notes`
+}
+
+export function renderFirstNoteReadme(ctx: InitSubRepoContext): string {
+  const noteTitle = generateNoteTitle(
+    '0001',
+    ctx.noteTitle,
+    buildRepoNotesUrl(ctx.repoName),
+  )
+  return `${noteTitle}\n${getNewNoteReadmeBody()}`
+}
+
+export function renderIndexMd(ctx: InitSubRepoContext): string {
+  return `---
+layout: home
+
+hero:
+  name: '${ctx.displayName}'
+  image:
+    src: /logo.png
+    alt: TNotes logo
+---
+
+<SidebarCard pending />
+`
+}
+
+export function renderTocMd(ctx: InitSubRepoContext): string {
+  return `- [ ] 0001. ${ctx.noteTitle}\n`
+}
+
+export function renderRootReadme(ctx: InitSubRepoContext): string {
+  return `# ${ctx.repoName}\n\n${ctx.description}\n`
+}
+
+export function buildPackageJsonTemplate(
+  coreVersion: string,
+): PackageJsonTemplate {
+  return {
+    type: 'module',
+    scripts: {
+      'tn:build': 'tnotes --build',
+      'tn:create-notes': 'tnotes --create-notes',
+      'tn:dev': 'tnotes --dev',
+      'tn:fix-timestamps': 'tnotes --fix-timestamps',
+      'tn:help': 'tnotes --help',
+      'tn:init-sub-repo': 'tnotes --init-sub-repo',
+      'tn:preview': 'tnotes --preview',
+      'tn:pull': 'tnotes --pull',
+      'tn:push': 'tnotes --push',
+      'tn:update': 'tnotes --update',
+      'tn:update-completed-count': 'tnotes --update-completed-count',
+    },
+    dependencies: {
+      '@tnotesjs/core': `^${coreVersion}`,
+    },
+    devDependencies: {
+      vite: '^7.3.1',
+      vitepress: '^1.6.3',
+      vue: '^3.5.27',
+    },
+  }
+}
+
+export function mergePackageJson(
+  existing: Record<string, unknown>,
+  template: PackageJsonTemplate,
+): Record<string, unknown> {
+  return {
+    ...existing,
+    type: template.type,
+    scripts: template.scripts,
+    dependencies: template.dependencies,
+    devDependencies: template.devDependencies,
+  }
+}
+
+export interface DynamicFileSpec {
+  relativePath: string
+  content: string
+}
+
+export function buildDynamicFiles(ctx: InitSubRepoContext): DynamicFileSpec[] {
+  return [
+    {
+      relativePath: '.tnotes.json',
+      content: `${JSON.stringify(buildTNotesConfig(ctx), null, 2)}\n`,
+    },
+    {
+      relativePath: 'package.json',
+      content: `${JSON.stringify(buildPackageJsonTemplate(ctx.coreVersion), null, 2)}\n`,
+    },
+    {
+      relativePath: 'index.md',
+      content: renderIndexMd(ctx),
+    },
+    {
+      relativePath: 'TOC.md',
+      content: renderTocMd(ctx),
+    },
+    {
+      relativePath: 'README.md',
+      content: renderRootReadme(ctx),
+    },
+    {
+      relativePath: join('notes', ctx.noteDirName, 'README.md'),
+      content: renderFirstNoteReadme(ctx),
+    },
+    {
+      relativePath: join('notes', ctx.noteDirName, '.tnotes.json'),
+      content: `${JSON.stringify(buildNoteConfig(ctx.noteUuid), null, 2)}\n`,
+    },
+  ]
+}
+
+export function isAlreadyInitialized(rootPath: string): boolean {
+  return existsSync(resolve(rootPath, '.tnotes.json'))
+}
+
+export function getInitializedConfigPath(rootPath: string): string {
+  return resolve(rootPath, '.tnotes.json')
+}
+
+export function resolvePackageJsonMerge(
+  targetPath: string,
+  template: PackageJsonTemplate,
+): { content: string; action: 'created' | 'updated' } {
+  if (!existsSync(targetPath)) {
+    return {
+      content: `${JSON.stringify(template, null, 2)}\n`,
+      action: 'created',
+    }
+  }
+
+  const existing = JSON.parse(readFileSync(targetPath, 'utf-8')) as Record<
+    string,
+    unknown
+  >
+  const merged = mergePackageJson(existing, template)
+  return {
+    content: `${JSON.stringify(merged, null, 2)}\n`,
+    action: 'updated',
+  }
+}
+
+export function buildManualSteps(ctx: InitSubRepoContext): string[] {
+  return [
+    'pnpm install — package.json 已更新，需重装依赖',
+    `创建 GitHub 仓库 https://github.com/${GITHUB_ORG}/${ctx.repoName}（若尚未创建）`,
+    'git init / git remote add origin（若尚未关联远程）',
+    'GitHub Pages：Settings → Build and deployment → Source 选 GitHub Actions',
+    'Repository secret：添加 TNOTES_DISPATCH_TOKEN（供 deploy.yml notify job 回调根库）',
+    `主题图标（可选）：确认 CDN 存在 icon--${ctx.topic}.svg，否则替换 .tnotes.json 中 root_item.icon.src`,
+    '本地验证：pnpm tn:dev',
+    '首次发布：push 到 main 触发 deploy workflow',
+  ]
+}

package/services/init-sub-repo/service.ts

@@ -0,0 +1,101 @@
+/**
+ * services/init-sub-repo/service.ts
+ *
+ * 子知识库初始化服务
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { dirname, join, resolve } from 'path'
+import { fileURLToPath } from 'url'
+
+import {
+  buildDynamicFiles,
+  buildInitContext,
+  buildPackageJsonTemplate,
+  resolvePackageJsonMerge,
+  STATIC_TEMPLATE_FILES,
+} from './initSubRepoLogic'
+
+import type { InitSubRepoInput, InitSubRepoWriteResult } from './initSubRepoLogic'
+
+export function getCorePackageRoot(fromModuleUrl: string): string {
+  let dir = dirname(fileURLToPath(fromModuleUrl))
+
+  while (dir !== dirname(dir)) {
+    const pkgPath = join(dir, 'package.json')
+    if (existsSync(pkgPath)) {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { name?: string }
+      if (pkg.name === '@tnotesjs/core') return dir
+    }
+    dir = dirname(dir)
+  }
+
+  throw new Error('无法定位 @tnotesjs/core 包根目录')
+}
+
+export function getTemplateRoot(fromModuleUrl: string): string {
+  return join(getCorePackageRoot(fromModuleUrl), 'templates', 'sub-repo')
+}
+
+export class InitSubRepoService {
+  private rootPath: string
+  private templateRoot: string
+
+  constructor(rootPath: string, templateRoot: string) {
+    this.rootPath = rootPath
+    this.templateRoot = templateRoot
+  }
+
+  static fromModuleUrl(moduleUrl: string, rootPath = process.cwd()): InitSubRepoService {
+    return new InitSubRepoService(rootPath, getTemplateRoot(moduleUrl))
+  }
+
+  writeScaffold(input: InitSubRepoInput): InitSubRepoWriteResult {
+    const ctx = buildInitContext(input)
+    const created: string[] = []
+    const skipped: string[] = []
+    const updated: string[] = []
+
+    for (const relativePath of STATIC_TEMPLATE_FILES) {
+      const targetPath = resolve(this.rootPath, relativePath)
+      if (existsSync(targetPath)) {
+        skipped.push(relativePath)
+        continue
+      }
+
+      const sourcePath = join(this.templateRoot, relativePath)
+      mkdirSync(dirname(targetPath), { recursive: true })
+      copyFileSync(sourcePath, targetPath)
+      created.push(relativePath)
+    }
+
+    const packageTemplate = buildPackageJsonTemplate(input.coreVersion)
+
+    for (const file of buildDynamicFiles(ctx)) {
+      const targetPath = resolve(this.rootPath, file.relativePath)
+
+      if (file.relativePath === 'package.json') {
+        const { content, action } = resolvePackageJsonMerge(
+          targetPath,
+          packageTemplate,
+        )
+        mkdirSync(dirname(targetPath), { recursive: true })
+        writeFileSync(targetPath, content, 'utf-8')
+        if (action === 'created') created.push(file.relativePath)
+        else updated.push(file.relativePath)
+        continue
+      }
+
+      if (existsSync(targetPath)) {
+        skipped.push(file.relativePath)
+        continue
+      }
+
+      mkdirSync(dirname(targetPath), { recursive: true })
+      writeFileSync(targetPath, file.content, 'utf-8')
+      created.push(file.relativePath)
+    }
+
+    return { created, skipped, updated }
+  }
+}

package/services/note/index.ts

@@ -0,0 +1,7 @@
+/**
+ * services/note/index.ts
+ *
+ * 笔记服务入口
+ */
+
+export { NoteService } from './service'