@tnotesjs/core 0.6.1 → 0.8.0

package/workspace/atomic.ts

@@ -0,0 +1,113 @@
+import { randomUUID } from 'node:crypto'
+import { constants as fsConstants } from 'node:fs'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import { WorkspaceError } from './errors'
+
+export interface AtomicWrite {
+  path: string
+  data: string | Uint8Array
+}
+
+interface OriginalFile {
+  path: string
+  existed: boolean
+  data?: Buffer
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath, fsConstants.F_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function stageWrite(write: AtomicWrite): Promise<string> {
+  await fs.mkdir(path.dirname(write.path), { recursive: true })
+  const temporaryPath = path.join(
+    path.dirname(write.path),
+    `.${path.basename(write.path)}.${randomUUID()}.tmp`,
+  )
+  const handle = await fs.open(temporaryPath, 'wx')
+  try {
+    await handle.writeFile(write.data)
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+  return temporaryPath
+}
+
+async function restoreOriginals(originals: OriginalFile[]): Promise<void> {
+  for (const original of originals) {
+    if (original.existed && original.data) {
+      const restorePath = await stageWrite({
+        path: original.path,
+        data: original.data,
+      })
+      await fs.rename(restorePath, original.path)
+    } else {
+      await fs.rm(original.path, { force: true })
+    }
+  }
+}
+
+/**
+ * Stage every file before replacing any target. If a replacement fails, the
+ * captured originals are restored. Directory mutations are deliberately kept
+ * outside this helper and validated before they run.
+ */
+export async function writeFilesAtomically(
+  writes: AtomicWrite[],
+): Promise<void> {
+  const uniqueWrites = new Map<string, AtomicWrite>()
+  for (const write of writes) uniqueWrites.set(write.path, write)
+  const normalizedWrites = [...uniqueWrites.values()]
+
+  const originals: OriginalFile[] = []
+  const staged: Array<{ target: string; temporary: string }> = []
+
+  try {
+    for (const write of normalizedWrites) {
+      const existed = await pathExists(write.path)
+      originals.push({
+        path: write.path,
+        existed,
+        data: existed ? await fs.readFile(write.path) : undefined,
+      })
+      staged.push({
+        target: write.path,
+        temporary: await stageWrite(write),
+      })
+    }
+
+    for (const item of staged) {
+      await fs.rename(item.temporary, item.target)
+    }
+  } catch (error) {
+    await Promise.allSettled(
+      staged.map((item) => fs.rm(item.temporary, { force: true })),
+    )
+    try {
+      await restoreOriginals(originals)
+    } catch (restoreError) {
+      throw new WorkspaceError(
+        'FILESYSTEM_ERROR',
+        '写入失败，并且无法完整恢复原文件',
+        {
+          cause: error instanceof Error ? error.message : String(error),
+          restoreCause:
+            restoreError instanceof Error
+              ? restoreError.message
+              : String(restoreError),
+        },
+      )
+    }
+    throw new WorkspaceError('FILESYSTEM_ERROR', '无法原子写入知识库文件', {
+      cause: error instanceof Error ? error.message : String(error),
+    })
+  }
+}

package/workspace/errors.ts

@@ -0,0 +1,27 @@
+export type WorkspaceErrorCode =
+  | 'WORKSPACE_DISPOSED'
+  | 'WORKSPACE_INVALID'
+  | 'WORKSPACE_READ_ONLY'
+  | 'NOTE_NOT_FOUND'
+  | 'NOTE_INDEX_EXHAUSTED'
+  | 'REVISION_CONFLICT'
+  | 'INVALID_TITLE'
+  | 'INVALID_TOC_ENTRY'
+  | 'INVALID_PATH'
+  | 'FILESYSTEM_ERROR'
+
+export class WorkspaceError extends Error {
+  readonly code: WorkspaceErrorCode
+  readonly details?: Record<string, unknown>
+
+  constructor(
+    code: WorkspaceErrorCode,
+    message: string,
+    details?: Record<string, unknown>,
+  ) {
+    super(message)
+    this.name = 'WorkspaceError'
+    this.code = code
+    this.details = details
+  }
+}

package/workspace/index.ts

@@ -0,0 +1,40 @@
+import { Workspace } from './workspace'
+
+import type { CreateWorkspaceOptions, TNotesWorkspace } from './types'
+
+export function createWorkspace(
+  options: CreateWorkspaceOptions,
+): TNotesWorkspace {
+  return new Workspace(options)
+}
+
+export { WorkspaceError } from './errors'
+export type { WorkspaceErrorCode } from './errors'
+export type {
+  AttachmentResult,
+  ChangedFile,
+  CreateNoteInput,
+  CreateTocGroupInput,
+  CreateWorkspaceOptions,
+  DeletePreviewItem,
+  DeleteTocEntryInput,
+  DeleteTocEntryPreview,
+  KnowledgeBaseSnapshot,
+  MoveTocEntryInput,
+  MutationResult,
+  NoteDocument,
+  NotePlacement,
+  RenameNoteInput,
+  RenameTocGroupInput,
+  SaveNoteInput,
+  TNotesWorkspace,
+  TocEntryRef,
+  UpdateNoteConfigInput,
+  WorkspaceDiagnostic,
+  WorkspaceHealth,
+  WorkspaceKnowledgeBaseConfig,
+  WorkspaceLogger,
+  WorkspaceNoteConfig,
+  WorkspaceNoteSummary,
+  WriteAttachmentInput,
+} from './types'

package/workspace/mutationQueue.ts

@@ -0,0 +1,28 @@
+export class MutationQueue {
+  private tail: Promise<void> = Promise.resolve()
+  private disposed = false
+
+  async run<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.disposed) {
+      throw new Error('Mutation queue has been disposed')
+    }
+
+    const previous = this.tail
+    let release!: () => void
+    this.tail = new Promise<void>((resolve) => {
+      release = resolve
+    })
+
+    await previous
+    try {
+      return await operation()
+    } finally {
+      release()
+    }
+  }
+
+  async dispose(): Promise<void> {
+    this.disposed = true
+    await this.tail
+  }
+}

package/workspace/paths.ts

@@ -0,0 +1,64 @@
+import path from 'node:path'
+
+import { WorkspaceError } from './errors'
+
+export interface WorkspacePaths {
+  root: string
+  config: string
+  toc: string
+  notes: string
+  sidebar: string
+  packageJson: string
+}
+
+export function createWorkspacePaths(rootPath: string): WorkspacePaths {
+  if (!rootPath || !path.isAbsolute(rootPath)) {
+    throw new WorkspaceError(
+      'INVALID_PATH',
+      '知识库路径必须是非空的绝对路径',
+      { rootPath },
+    )
+  }
+
+  const root = path.normalize(path.resolve(rootPath))
+  return {
+    root,
+    config: path.join(root, '.tnotes.json'),
+    toc: path.join(root, 'TOC.md'),
+    notes: path.join(root, 'notes'),
+    sidebar: path.join(root, 'sidebar.json'),
+    packageJson: path.join(root, 'package.json'),
+  }
+}
+
+export function assertPathInside(parent: string, target: string): void {
+  const relative = path.relative(parent, target)
+  if (
+    relative === '' ||
+    (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))
+  ) {
+    return
+  }
+
+  throw new WorkspaceError('INVALID_PATH', '目标路径超出允许范围', {
+    parent,
+    target,
+  })
+}
+
+export function sanitizeFileName(fileName: string): string {
+  const value = fileName.trim()
+  if (
+    !value ||
+    value === '.' ||
+    value === '..' ||
+    value.includes('/') ||
+    value.includes('\\') ||
+    value.includes('\0')
+  ) {
+    throw new WorkspaceError('INVALID_PATH', '附件文件名不合法', {
+      fileName,
+    })
+  }
+  return value
+}

package/workspace/reconcile.test.ts

@@ -0,0 +1,300 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { createWorkspace } from './index'
+import { planReconcile } from './reconcile'
+
+import type { KnowledgeBaseSnapshot } from './types'
+import type { TocTreeNode } from '../utils/tocHelpers'
+
+const temporaryDirectories: string[] = []
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories.splice(0).map((directory) =>
+      fs.rm(directory, { recursive: true, force: true }),
+    ),
+  )
+})
+
+function knowledgeBaseConfig(id: string, repoName: string) {
+  return {
+    id,
+    author: 'tnotesjs',
+    repoName,
+    keywords: [repoName],
+    sidebarShowNoteId: false,
+    ignore_dirs: [],
+    socialLinks: [],
+    menuItems: [],
+    root_item: {
+      title: repoName,
+      completed_notes_count: {},
+      details: repoName,
+      link: '/',
+    },
+  }
+}
+
+function noteConfig(id: string, done = false) {
+  return {
+    bilibili: [],
+    tnotes: [],
+    yuque: [],
+    done,
+    enableDiscussions: false,
+    description: '',
+    id,
+  }
+}
+
+async function createFixture(input?: {
+  notes?: Array<{
+    index: string
+    title: string
+    id: string
+    done?: boolean
+  }>
+  toc?: string
+}) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'tnotes-core-reconcile-'))
+  temporaryDirectories.push(root)
+  const notes =
+    input?.notes ?? [
+      { index: '0016', title: 'Alpha', id: 'note-alpha' },
+      { index: '0017', title: 'Beta', id: 'note-beta' },
+    ]
+  await fs.mkdir(path.join(root, 'notes'))
+  await fs.writeFile(
+    path.join(root, '.tnotes.json'),
+    JSON.stringify(knowledgeBaseConfig('kb-reconcile', 'TNotes.reconcile'), null, 2),
+  )
+  await fs.writeFile(path.join(root, 'README.md'), 'legacy root readme\n')
+  for (const note of notes) {
+    const directory = path.join(root, 'notes', `${note.index}. ${note.title}`)
+    await fs.mkdir(directory)
+    await fs.writeFile(
+      path.join(directory, '.tnotes.json'),
+      `${JSON.stringify(noteConfig(note.id, note.done), null, 2)}\n`,
+    )
+    await fs.writeFile(
+      path.join(directory, 'README.md'),
+      `# ${note.title}\n\n## Intro\n`,
+    )
+  }
+  await fs.writeFile(
+    path.join(root, 'TOC.md'),
+    input?.toc ?? `${notes.map((note) => `- [ ] ${note.index}. ${note.title}`).join('\n')}\n`,
+  )
+  await fs.writeFile(path.join(root, 'sidebar.json'), '[]\n')
+  return root
+}
+
+/** A minimal but fully-shaped snapshot for pure planner tests. */
+function snapshotWith(input: {
+  notes: Array<{ index: string; title: string; dirName: string; uuid: string; config: { done: boolean } }>
+  toc: TocTreeNode[]
+  diagnostics: KnowledgeBaseSnapshot['health']['diagnostics']
+}): KnowledgeBaseSnapshot {
+  return {
+    id: 'kb-reconcile',
+    rootPath: '/tmp/fixture',
+    config: knowledgeBaseConfig('kb-reconcile', 'TNotes.reconcile'),
+    health: { status: 'invalid' as const, diagnostics: input.diagnostics },
+    toc: input.toc,
+    sidebar: [],
+    notes: input.notes.map((note) => ({
+      uuid: note.uuid,
+      index: note.index,
+      title: note.title,
+      dirName: note.dirName,
+      directoryPath: `/tmp/fixture/notes/${note.dirName}`,
+      readmePath: `/tmp/fixture/notes/${note.dirName}/README.md`,
+      configPath: `/tmp/fixture/notes/${note.dirName}/.tnotes.json`,
+      config: note.config,
+      revision: 'rev',
+    })),
+    revision: 'rev-snapshot',
+  }
+}
+
+describe('planReconcile', () => {
+  it('缺 config 的目录进入 trashDirs；其余保持不变', () => {
+    const plan = planReconcile(
+      snapshotWith({
+        notes: [],
+        toc: [],
+        diagnostics: [
+          {
+            code: 'NOTE_CONFIG_MISSING',
+            message: '笔记 X 缺少 .tnotes.json',
+            severity: 'error',
+            path: 'notes/0005. X/.tnotes.json',
+          },
+          {
+            code: 'NOTE_INDEX_DUPLICATE',
+            message: '笔记编号 0005 重复',
+            severity: 'error',
+            path: 'notes/0005. X',
+          },
+        ],
+      }),
+    )
+    expect(plan.trashDirs).toEqual(['0005. X'])
+  })
+
+  it('保留分组结构；丢弃无法解析的笔记行；按需追加缺失的合法笔记（根级、按索引排序）', () => {
+    const plan = planReconcile(
+      snapshotWith({
+        notes: [
+          { index: '0016', title: 'A', dirName: '0016. A', uuid: 'u1', config: { done: false } },
+          { index: '0024', title: 'New', dirName: '0024. New', uuid: 'u24', config: { done: false } },
+        ],
+        toc: [
+          {
+            kind: 'folder',
+            title: '组件',
+            indent: 0,
+            tocLineIndex: 0,
+            children: [
+              { kind: 'note', noteIndex: '0016', indent: 1, tocLineIndex: 1, children: [] },
+              // 目录已不存在（0017 不在 notes 里）→ 应被丢弃
+              { kind: 'note', noteIndex: '0017', indent: 1, tocLineIndex: 2, children: [] },
+            ],
+          },
+        ],
+        diagnostics: [],
+      }),
+    )
+    expect(plan.trashDirs).toEqual([])
+    const folder = plan.tree[0]
+    expect(folder.kind).toBe('folder')
+    if (folder.kind !== 'folder') return
+    expect(folder.children.map((node) => (node.kind === 'note' ? node.noteIndex : null))).toEqual([
+      '0016',
+    ])
+    // 追加到根级、按索引排序
+    expect(plan.tree.at(-1)).toMatchObject({ kind: 'note', noteIndex: '0024', indent: 0 })
+  })
+})
+
+describe('workspace.toc.reconcileFromFiles', () => {
+  it('软删缺配置目录 + 补缺失行 + 丢弃失联行，幂等', async () => {
+    const root = await createFixture({
+      // 0024 合法但不在 TOC；0010 在 TOC 但目录不存在
+      notes: [
+        { index: '0016', title: 'Alpha', id: 'note-alpha' },
+        { index: '0017', title: 'Beta', id: 'note-beta' },
+        { index: '0024', title: 'Gamma', id: 'note-gamma' },
+      ],
+      toc: [
+        '- 组件',
+        '  - [ ] 0016. Alpha',
+        '  - [ ] 0017. Beta',
+        '- [ ] 0010. 幽灵笔记',
+        '',
+      ].join('\n'),
+    })
+    // 手动制造一个缺 config 的目录
+    const brokenDir = path.join(root, 'notes', '0005. Broken')
+    await fs.mkdir(brokenDir)
+    await fs.writeFile(path.join(brokenDir, 'README.md'), '# Broken\n')
+
+    const workspace = createWorkspace({ rootPath: root })
+    const result = await workspace.toc.reconcileFromFiles()
+
+    // 1) 软删：目录进了 .trash
+    expect(await exists(path.join(brokenDir))).toBe(false)
+    expect(await exists(path.join(root, 'notes', '.trash', '0005. Broken'))).toBe(true)
+    expect(result.changedFiles.some((file) => file.kind === 'trashed')).toBe(true)
+
+    // 2) TOC：0016/0017 保留（组内）+ 0024 追加根级 + 0010 失联行被清
+    const toc = await fs.readFile(path.join(root, 'TOC.md'), 'utf-8')
+    expect(toc).toContain('0016. Alpha')
+    expect(toc).toContain('0017. Beta')
+    expect(toc).toContain('- [ ] 0024. Gamma')
+    expect(toc).not.toContain('0010')
+    expect(toc).not.toContain('0005. Broken')
+
+    // 3) sidebar 重建
+    const sidebar = await fs.readFile(path.join(root, 'sidebar.json'), 'utf-8')
+    expect(sidebar).not.toBe('[]\n')
+
+    // 4) 愈合后健康恢复
+    expect(result.value.health.status).toBe('ready')
+
+    // 5) 幂等：第二次不再产生变更
+    const second = await workspace.toc.reconcileFromFiles()
+    expect(second.changedFiles).toEqual([])
+
+    await workspace.dispose()
+  })
+
+  it('TOC.md 缺失时从零构建（全部合法笔记排根级）', async () => {
+    const root = await createFixture({
+      notes: [
+        { index: '0001', title: 'Alpha', id: 'note-alpha' },
+        { index: '0002', title: 'Beta', id: 'note-beta' },
+      ],
+    })
+    await fs.rm(path.join(root, 'TOC.md'))
+
+    const workspace = createWorkspace({ rootPath: root })
+    const result = await workspace.toc.reconcileFromFiles()
+    const toc = await fs.readFile(path.join(root, 'TOC.md'), 'utf-8')
+    expect(toc).toContain('- [ ] 0001. Alpha')
+    expect(toc).toContain('- [ ] 0002. Beta')
+    expect(result.value.health.status).toBe('ready')
+    await workspace.dispose()
+  })
+
+  it('根配置缺失时拒绝（WORKSPACE_INVALID），不静默改动', async () => {
+    const root = await createFixture()
+    await fs.rm(path.join(root, '.tnotes.json'))
+
+    const workspace = createWorkspace({ rootPath: root })
+    await expect(workspace.toc.reconcileFromFiles()).rejects.toThrow(/知识库配置异常/)
+    await workspace.dispose()
+  })
+
+  it('同名笔记二次软删不报错，进入带时间戳的目标（不覆盖第一次回收内容）', async () => {
+    const root = await createFixture({
+      notes: [{ index: '0001', title: 'Alpha', id: 'note-alpha' }],
+    })
+    const workspace = createWorkspace({ rootPath: root })
+    const noteDir = path.join(root, 'notes', '0001. Alpha')
+
+    // 第一次破坏：config 丢失 → 软删为 .trash/0001. Alpha
+    await fs.rm(path.join(noteDir, '.tnotes.json'))
+    await workspace.toc.reconcileFromFiles()
+    expect(await exists(path.join(root, 'notes', '.trash', '0001. Alpha'))).toBe(true)
+
+    // 重建同名合法笔记，再破坏 → 不应报错，目标带时间戳
+    await fs.mkdir(noteDir, { recursive: true })
+    await fs.writeFile(
+      path.join(noteDir, '.tnotes.json'),
+      `${JSON.stringify(noteConfig('note-alpha-2'), null, 2)}\n`,
+    )
+    await fs.writeFile(path.join(noteDir, 'README.md'), '# Alpha\n')
+    await fs.rm(path.join(noteDir, '.tnotes.json'))
+    const result = await workspace.toc.reconcileFromFiles()
+
+    const trashEntries = await fs.readdir(path.join(root, 'notes', '.trash'))
+    expect(trashEntries.length).toBe(2)
+    expect(trashEntries).toContain('0001. Alpha')
+    expect(trashEntries.some((name) => name.startsWith('0001. Alpha-'))).toBe(true)
+    expect(result.changedFiles.some((file) => file.kind === 'trashed')).toBe(true)
+    await workspace.dispose()
+  })
+})
+
+async function exists(target: string): Promise<boolean> {
+  try {
+    await fs.stat(target)
+    return true
+  } catch {
+    return false
+  }
+}

package/workspace/reconcile.ts

@@ -0,0 +1,95 @@
+import type { KnowledgeBaseSnapshot } from './types'
+import type { TocTreeNode } from '../utils/tocHelpers'
+
+/**
+ * Diagnostics that mark a note directory as invalid enough to soft-delete.
+ * - NOTE_CONFIG_MISSING: notes/<dir>/.tnotes.json absent
+ * - NOTE_CONFIG_INVALID: config unparsable or missing a valid `id`
+ * Others (duplicate index/id, missing README) are reported but NOT auto-deleted —
+ * duplicates cannot be auto-resolved, and README absence is not our rule.
+ */
+const NOTE_CONFIG_DIAGNOSTIC_CODES = new Set([
+  'NOTE_CONFIG_MISSING',
+  'NOTE_CONFIG_INVALID'
+])
+
+export interface ReconcilePlan {
+  /** Note dir names to soft-delete (move to notes/.trash/), sorted. */
+  trashDirs: string[]
+  /**
+   * Rebuilt TOC tree: keeps the existing structure/order/folders, but note rows
+   * not resolvable against the live notes dir are dropped by the serializer and
+   * valid notes missing from the TOC are appended at root level (by index).
+   */
+  tree: TocTreeNode[]
+}
+
+/** Directory name from a note-config diagnostic path (`…/notes/<dir>/.tnotes.json`). */
+function dirFromConfigDiagnostic(path: string | null | undefined): string | null {
+  if (!path) return null
+  const match = path.replace(/\\/g, '/').match(/(?:^|\/)notes\/([^/]+)\/\.tnotes\.json$/)
+  return match ? match[1] : null
+}
+
+/**
+ * Pure planner: derives the reconcile outcome from one scanned snapshot.
+ * The filesystem is the truth; TNotes note indexes are unique + immutable, so
+ * note rows are matched to disk directories by index.
+ */
+export function planReconcile(snapshot: KnowledgeBaseSnapshot): ReconcilePlan {
+  const seen = new Set<string>()
+  const trashDirs: string[] = []
+  for (const diagnostic of snapshot.health.diagnostics) {
+    if (!NOTE_CONFIG_DIAGNOSTIC_CODES.has(diagnostic.code)) continue
+    const dir = dirFromConfigDiagnostic(diagnostic.path)
+    if (dir && !seen.has(dir)) {
+      seen.add(dir)
+      trashDirs.push(dir)
+    }
+  }
+  trashDirs.sort((a, b) => a.localeCompare(b))
+
+  const validIndexes = new Set(snapshot.notes.map((note) => note.index))
+
+  // Clean tree: keep folders (even if emptied), drop note rows that no longer
+  // resolve against the live notes dir.
+  const clean = (nodes: TocTreeNode[]): TocTreeNode[] => {
+    const next: TocTreeNode[] = []
+    for (const node of nodes) {
+      if (node.kind === 'folder') {
+        next.push({ ...node, children: clean(node.children) })
+        continue
+      }
+      if (validIndexes.has(node.noteIndex)) {
+        next.push({ ...node, children: clean(node.children) })
+      }
+    }
+    return next
+  }
+
+  const present = new Set<string>()
+  const walk = (nodes: TocTreeNode[]): void => {
+    for (const node of nodes) {
+      if (node.kind === 'note') present.add(node.noteIndex)
+      walk(node.children)
+    }
+  }
+  walk(snapshot.toc)
+
+  const missing = snapshot.notes
+    .filter((note) => !present.has(note.index))
+    .sort((left, right) => left.index.localeCompare(right.index))
+
+  const tree: TocTreeNode[] = [
+    ...clean(snapshot.toc),
+    ...missing.map((note) => ({
+      kind: 'note' as const,
+      noteIndex: note.index,
+      indent: 0,
+      tocLineIndex: 0,
+      children: [] as TocTreeNode[]
+    }))
+  ]
+
+  return { trashDirs, tree }
+}