@tnotesjs/core 0.7.0 → 0.8.0

package/vitepress/configs/markdown.config.ts

@@ -4,18 +4,21 @@
  * Markdown 配置
  */
 
-import fs from 'fs'
 import markdownItContainer from 'markdown-it-container'
 import mila from 'markdown-it-link-attributes'
 import markdownItTaskLists from 'markdown-it-task-lists'
-import path from 'path'
 
 import { generateAnchor } from '../../utils'
 import {
   normalizeMindmapMarkdown,
   parseMindmapFence,
-  parseMindmapReference,
 } from '../components/MindmapPreview/markdown'
+// Pure helper only — do not import `@tnotesjs/ui` root from Node config
+// (package entry is .ts; Node cannot strip types under node_modules).
+import {
+  parseFootprintsDatetime,
+  parseFootprintsSource,
+} from '@tnotesjs/ui/footprints-parse'
 
 import type MarkdownIt from 'markdown-it'
 import type { MarkdownOptions } from 'vitepress'
@@ -47,15 +50,18 @@ const simpleMermaidMarkdown = (md: MarkdownIt) => {
 
   md.renderer.rules.fence = (tokens, index, options, env, slf) => {
     const token = tokens[index]
+    const parts = token.info.trim().split(/\s+/).filter(Boolean)
 
-    // 检查是否为 mermaid 代码块
-    if (token.info.trim() === 'mermaid') {
+    // `mermaid` or `mermaid center`
+    if (parts[0] === 'mermaid') {
       try {
+        const centered = parts.slice(1).some((part) => part.toLowerCase() === 'center')
         const key = `mermaid-${Date.now()}-${Math.random()
           .toString(36)
           .substr(2, 9)}`
         const content = token.content
-        return `<Mermaid id="${key}" graph="${encodeURIComponent(content)}" />`
+        const centerAttr = centered ? ' :center="true"' : ''
+        return `<Mermaid id="${key}" graph="${encodeURIComponent(content)}"${centerAttr} />`
       } catch (err) {
         return `<pre>${err}</pre>`
       }
@@ -81,25 +87,10 @@ function configureMindmapFence(md: MarkdownIt) {
     const info = token.info.trim()
     const fenceOptions = parseMindmapFence(info)
     if (!fenceOptions) return fence(tokens, index, options, env, slf)
-    let content = token.content
-    const firstNonEmptyLine = content.split('\n').find((line) => line.trim()) ?? ''
-    const reference = parseMindmapReference(firstNonEmptyLine)
-
-    if (reference) {
-      const possibleRel = env?.relativePath || env?.path || env?.filePath || env?.file || ''
-      const refFullPath = path.isAbsolute(reference.path)
-        ? reference.path
-        : path.resolve(process.cwd(), possibleRel ? path.dirname(possibleRel) : '', reference.path)
-      try {
-        content = fs.readFileSync(refFullPath, 'utf8')
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error)
-        content = `- Failed to load referenced file: ${reference.path}\n  - Error: ${message}`
-      }
-    }
-
-    content = normalizeMindmapMarkdown(content, {
-      title: fenceOptions.title || reference?.title,
+    // Mindmap nodes must live in the fence body. External `<<<` includes are
+    // no longer resolved here (body-level VitePress snippets remain separate).
+    const content = normalizeMindmapMarkdown(token.content, {
+      title: fenceOptions.title,
     })
     const props = [
       `content="${encodeURIComponent(content.trim())}"`,
@@ -107,7 +98,7 @@ function configureMindmapFence(md: MarkdownIt) {
         ? ''
         : `:initialExpandLevel="${fenceOptions.initialExpandLevel}"`,
     ].filter(Boolean).join(' ')
-    return `<MindmapPreview ${props}></MindmapPreview>\n`
+    return `<Mindmap ${props}></Mindmap>\n`
   }
 }
 
@@ -187,6 +178,156 @@ function configureSwiperContainer(md: MarkdownIt) {
   })
 }
 
+/** Escape text for HTML element bodies (not attributes). */
+function escapeHtmlText(s: string) {
+  return s.replace(
+    /[&<>"']/g,
+    (ch) =>
+      ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch] as string
+  )
+}
+
+/**
+ * `::: footprints 2025-01-22 23:47` → Footprints Vue block.
+ * Prefer token-based extraction (source line maps are unreliable in VitePress).
+ * Text goes through encoded props; images use a slot so Vite rewrites asset URLs.
+ */
+function extractFootprintsPayloadFromTokens(tokens: any[], idx: number) {
+  const meta = String(tokens[idx].info || '')
+    .trim()
+    .replace(/^footprints\s*/i, '')
+  const times = parseFootprintsDatetime(meta)
+  const paragraphs: string[] = []
+  const images: string[] = []
+  let otherInfo = ''
+  let inOther = false
+
+  for (let i = idx + 1; i < tokens.length; i++) {
+    const t = tokens[i]
+    if (t.type === 'container_footprints_close') break
+    if (t.type !== 'inline') continue
+
+    const childImgs: string[] = []
+    if (Array.isArray(t.children)) {
+      for (const c of t.children) {
+        if (c.type === 'image') {
+          const src = c.attrGet?.('src') || c.attrs?.find((a: string[]) => a[0] === 'src')?.[1]
+          if (src) childImgs.push(src)
+        }
+      }
+    }
+
+    const content = String(t.content || '').trim()
+    if (content === '---') {
+      inOther = true
+      continue
+    }
+    if (childImgs.length) {
+      // Treat as image block when the inline is image-only (ignore bare alt text).
+      const withoutImgs = content.replace(/!\[[^\]]*\]\([^)]+\)/g, '').trim()
+      if (!withoutImgs) {
+        images.push(...childImgs)
+        continue
+      }
+    }
+    const imgOnly = content.match(/^!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)$/)
+    if (imgOnly) {
+      images.push(imgOnly[2])
+      continue
+    }
+    if (!content) continue
+    if (inOther) otherInfo = otherInfo ? `${otherInfo}\n${content}` : content
+    else paragraphs.push(content)
+  }
+
+  return { times, paragraphs, images, otherInfo }
+}
+
+function configureFootprintsContainer(md: MarkdownIt) {
+  md.use(markdownItContainer, 'footprints', {
+    validate: (params: string) => /^footprints(\s|$)/i.test(params.trim()),
+    render: (tokens: any[], idx: number, _opts: unknown, env: any) => {
+      if (tokens[idx].nesting !== 1) return ''
+
+      // Extract BEFORE hiding/clearing tokens.
+      let payload = extractFootprintsPayloadFromTokens(tokens, idx)
+
+      // Optional enrichment from source slice when tokens missed content.
+      const startLine = tokens[idx].map?.[0] ?? 0
+      let endLine = startLine
+      for (let i = idx + 1; i < tokens.length; i++) {
+        if (tokens[i].type === 'container_footprints_close') {
+          endLine = tokens[i].map?.[0] ?? endLine
+          break
+        }
+      }
+      const raw = String(env?.src ?? env?.source ?? '')
+      if (raw && endLine > startLine) {
+        const slice = raw.split(/\r?\n/).slice(startLine, endLine + 1).join('\n')
+        const fromSource = parseFootprintsSource(
+          slice.includes(':::') ? slice : `::: ${tokens[idx].info}\n${slice}\n:::`
+        )
+        if (!payload.paragraphs.length && fromSource.paragraphs.length) {
+          payload = { ...payload, paragraphs: fromSource.paragraphs }
+        }
+        if (!payload.images.length && fromSource.images.length) {
+          payload = { ...payload, images: fromSource.images }
+        }
+        if (!payload.otherInfo && fromSource.otherInfo) {
+          payload = { ...payload, otherInfo: fromSource.otherInfo }
+        }
+        if (!payload.times.length && fromSource.times.length) {
+          payload = { ...payload, times: fromSource.times }
+        }
+      }
+
+      for (let i = idx + 1; i < tokens.length; i++) {
+        if (tokens[i].type === 'container_footprints_close') break
+        tokens[i].hidden = true
+        tokens[i].content = ''
+        if (Array.isArray(tokens[i].children)) {
+          for (const child of tokens[i].children) {
+            child.hidden = true
+            child.content = ''
+          }
+          tokens[i].children = []
+        }
+      }
+
+      const enc = (value: unknown) =>
+        encodeURIComponent(JSON.stringify(value)).replace(/'/g, '%27')
+      const bindExpr = (value: unknown) =>
+        "JSON.parse(decodeURIComponent('" + enc(value) + "'))"
+      const imageSlot = payload.images
+        .map((src, i) => {
+          return (
+            '<img src="' +
+            escapeHtmlText(src) +
+            '" @click="openModal(' +
+            String(i) +
+            ')" />'
+          )
+        })
+        .join('\n')
+      const openTag =
+        '<Footprints :times="' +
+        bindExpr(payload.times) +
+        '" :paragraphs="' +
+        bindExpr(payload.paragraphs) +
+        '" :other-info="' +
+        bindExpr(payload.otherInfo) +
+        '">'
+      if (!payload.images.length) return openTag + '</Footprints>\n'
+      return (
+        openTag +
+        '\n<template #image-list="{ openModal }">\n' +
+        imageSlot +
+        '\n</template>\n</Footprints>\n'
+      )
+    },
+  })
+}
+
 /**
  * Markdown 配置
  */
@@ -220,6 +361,9 @@ export function getMarkdownConfig(): MarkdownOptions {
 
       // 添加 Swiper 支持
       configureSwiperContainer(md)
+
+      // Footprints 容器（Type A）
+      configureFootprintsContainer(md)
     },
     anchor: {
       slugify: generateAnchor,

package/vitepress/theme/index.ts

@@ -13,23 +13,19 @@
  */
 
 import DefaultTheme from 'vitepress/theme'
-
+import { BilibiliVideo, WordList, Mermaid, Mindmap, Footprints } from '@tnotesjs/ui'
 import { initTnotesSearchIndexHmr } from '../client/localSearchIndexBridge'
-import BilibiliOutsidePlayer from '../components/BilibiliOutsidePlayer/BilibiliOutsidePlayer.vue'
 import Discussions from '../components/Discussions/Discussions.vue'
-import EnWordList from '../components/EnWordList/EnWordList.vue'
-import Footprints from '../components/Footprints/Footprints.vue'
 import { useRenameOverlay } from '../components/Layout/composables/useRenameOverlay'
 import { redirectAfterRename } from '../components/Layout/composables/useRenameRedirect'
 import Layout from '../components/Layout/Layout.vue'
-import Mermaid from '../components/Mermaid/Mermaid.vue'
-import MindmapPreview from '../components/MindmapPreview/MindmapPreview.vue'
 import NotesTable from '../components/NotesTable/NotesTable.vue'
 import SidebarCard from '../components/SidebarCard/SidebarCard.vue'
 import Tooltip from '../components/Tooltip/Tooltip.vue'
 
 
 import type { Theme, EnhanceAppContext } from 'vitepress'
+import '@tnotesjs/ui/styles/tokens.css'
 import './styles/index.scss'
 
 /**
@@ -37,18 +33,18 @@ import './styles/index.scss'
  */
 function registerCoreComponents(ctx: EnhanceAppContext) {
   const { app } = ctx
-  app.component('BilibiliOutsidePlayer', BilibiliOutsidePlayer)
-  app.component('B', BilibiliOutsidePlayer)
+  app.component('BilibiliVideo', BilibiliVideo)
+  // Legacy full tag until knowledge-base migration; short aliases B/E/N/F are removed.
+  app.component('BilibiliOutsidePlayer', BilibiliVideo)
+  app.component('WordList', WordList)
+  app.component('EnWordList', WordList)
   app.component('Discussions', Discussions)
-  app.component('EnWordList', EnWordList)
-  app.component('E', EnWordList)
   app.component('Footprints', Footprints)
-  app.component('F', Footprints)
   app.component('SidebarCard', SidebarCard)
-  app.component('MindmapPreview', MindmapPreview)
+  app.component('Mindmap', Mindmap)
+  app.component('MindmapPreview', Mindmap)
   app.component('Mermaid', Mermaid)
   app.component('NotesTable', NotesTable)
-  app.component('N', NotesTable)
   app.component('Tooltip', Tooltip)
 }
 

package/vitepress/theme/styles/base.scss

@@ -13,6 +13,21 @@
   /* 品牌色 */
   --vp-c-brand-1: #646cff;
   --vp-c-brand-2: #747bff;
+
+  /* Map VitePress tokens onto @tnotesjs/ui --tn-* */
+  --tn-c-brand: var(--vp-c-brand-1);
+  --tn-c-text: var(--vp-c-text-1);
+  --tn-c-text-2: var(--vp-c-text-2);
+  --tn-c-bg: var(--vp-c-bg);
+  --tn-c-bg-soft: var(--vp-c-bg-soft);
+  --tn-c-bg-elv: var(--vp-c-bg-elv);
+  --tn-c-divider: var(--vp-c-divider);
+  --tn-c-danger: var(--vp-c-danger-1);
+  --tn-c-success-soft: var(--vp-c-green-soft);
+  --tn-c-danger-soft: var(--vp-c-danger-soft);
+  --tn-c-default-soft: var(--vp-c-default-soft);
+  --tn-shadow-2: var(--vp-shadow-2);
+  --tn-font-mono: var(--vp-font-family-mono);
 }
 
 /* #endregion */

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
+}