project-node-memory 0.0.0-stage → 1.0.1

package/lib/engine/registry.js

@@ -0,0 +1,241 @@
+/**
+ * registry —— 库定位（工作区优先，注册表兜底）。
+ *
+ * 三种来源，优先级从高到低：
+ * 1. 工具参数 `lib`（技能目录或 .nodekb 路径）——受工作区/已注册路径白名单约束
+ * 2. config.libraries 里显式声明的 { 名字: 技能目录 }
+ * 3. 注册表 JSON（`{"libraries":{"名字":{"path":"技能目录"}}}`，与 Python 版 kb_registry.json 同格式）
+ * 4. 工作区自带 `.nodekb`（名字固定为 workspace）
+ */
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+export const DEFAULT_KB = 'workspace'
+
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function isFile(p) {
+  try {
+    return fs.statSync(p).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** child 是否位于 parent 之内（含相等） */
+export function isInside(child, parent) {
+  const rel = path.relative(path.resolve(parent), path.resolve(child))
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+}
+
+export function defaultRegistryPaths(workspace) {
+  const out = [path.join(os.homedir(), '.dsh', 'nodekb', 'registry.json')]
+  for (const p of [path.join(workspace, 'kb_registry.json'), path.join(workspace, '.nodekb', 'kb_registry.json')]) {
+    if (isFile(p)) out.push(p)
+  }
+  return out
+}
+
+export function readRegistryFile(file) {
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'))
+    const libs = data && typeof data === 'object' ? data.libraries : null
+    if (!libs || typeof libs !== 'object') return {}
+    const out = {}
+    for (const [name, info] of Object.entries(libs)) {
+      if (info && typeof info.path === 'string' && info.path) out[name] = { path: info.path, registry: file }
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
+/** 合并多个注册表（先出现的优先） */
+export function loadRegistries(files, inline) {
+  const merged = new Map()
+  for (const [name, dir] of Object.entries(inline || {})) {
+    if (typeof dir === 'string' && dir) merged.set(name, { path: dir, registry: 'config' })
+  }
+  for (const f of files || []) {
+    for (const [name, entry] of Object.entries(readRegistryFile(f))) {
+      if (!merged.has(name)) merged.set(name, entry)
+    }
+  }
+  return merged
+}
+
+function workspaceBase(workspace) {
+  const nodekb = path.join(workspace, '.nodekb')
+  return isDir(nodekb) ? { name: DEFAULT_KB, base: workspace, nodekb, origin: 'workspace' } : null
+}
+
+function safeReaddir(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 在工作区里找库（有界 BFS，默认下钻 2 层）。
+ * 约定位置优先，但 <root>/packages/<包>/.nodekb 这种单仓多包也能发现。
+ * 跳过 node_modules/.git/dist/build 与点目录；budget 是 readdir 次数上限，
+ * 面板每次加载都会调，不能把整棵树走一遍。
+ */
+const SKIP_DIR = new Set(['node_modules', 'dist', 'build', 'out', 'target', 'coverage', '.git'])
+
+export function discoverLibraries(root, { depth = 2, budget = 300, limit = 60 } = {}) {
+  const ws = path.resolve(root || '.')
+  const out = []
+  const seen = new Set()
+  const push = (dir, rel, origin) => {
+    const nodekb = path.join(dir, '.nodekb')
+    if (!isDir(nodekb) || seen.has(nodekb)) return
+    seen.add(nodekb)
+    const parts = rel ? rel.split(/[\\/]/) : []
+    const isSkill = parts.length >= 2 && parts[parts.length - 2] === 'skills'
+    const name = !parts.length ? DEFAULT_KB : isSkill ? parts[parts.length - 1] : parts.join('/')
+    out.push({ name, path: dir, nodekb, exists: true, origin })
+  }
+  push(ws, '', 'workspace')
+  // 技能自带的知识库是约定位置，单独直查（不进 BFS，因为 .dsh 是点目录）
+  const scanSkills = (base, prefix) => {
+    for (const e of safeReaddir(path.join(base, '.dsh', 'skills'))) {
+      if (!e.isDirectory() || e.name.startsWith('.')) continue
+      push(path.join(base, '.dsh', 'skills', e.name), (prefix ? prefix + '/' : '') + '.dsh/skills/' + e.name, 'discovered')
+      if (out.length >= limit) return
+    }
+  }
+  scanSkills(ws, '')
+  const queue = [{ dir: ws, rel: '', level: 0 }]
+  let spent = 0
+  while (queue.length && spent < budget && out.length < limit) {
+    const cur = queue.shift()
+    if (cur.level >= depth) continue
+    let entries
+    spent += 1
+    try {
+      entries = fs.readdirSync(cur.dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const e of entries) {
+      if (out.length >= limit || spent >= budget) break
+      if (!e.isDirectory() || e.name.startsWith('.') || SKIP_DIR.has(e.name)) continue
+      const rel = cur.rel ? cur.rel + '/' + e.name : e.name
+      const dir = path.join(cur.dir, e.name)
+      push(dir, rel, 'discovered')
+      if (cur.level === 0) scanSkills(dir, e.name)
+      queue.push({ dir, rel, level: cur.level + 1 })
+    }
+  }
+  return out
+}
+
+/**
+ * 定位库根（返回 .nodekb 目录）。
+ * @throws 带可行动提示的错误
+ */
+export function resolveLibrary({ kb, lib, workspace, config } = {}) {
+  const ws = path.resolve(workspace || process.cwd())
+  const registries = loadRegistries(
+    config && config.registries ? config.registries : defaultRegistryPaths(ws),
+    config && config.libraries,
+  )
+
+  // 1) 显式路径
+  if (lib) {
+    const p = path.resolve(ws, lib)
+    const nodekb = path.basename(p) === '.nodekb' ? p : path.join(p, '.nodekb')
+    if (!isDir(nodekb)) throw new Error(`库目录不存在: ${nodekb}（你传入: ${lib}）`)
+    const allowed = [ws, ...[...registries.values()].map((e) => e.path)]
+    if (!allowed.some((root) => isInside(nodekb, root))) {
+      throw new Error(
+        `拒绝访问工作区外的库: ${nodekb}\n` +
+          `允许范围 = 工作区 ${ws} + 已注册库。需要长期使用请在插件配置 config.libraries 里登记。`,
+      )
+    }
+    return { name: path.basename(nodekb), base: path.dirname(nodekb), nodekb, origin: 'lib' }
+  }
+
+  // 2) 名字
+  const name = kb && String(kb).trim()
+  if (name) {
+    const entry = registries.get(name)
+    if (entry) {
+      const nodekb = path.join(entry.path, '.nodekb')
+      if (!isDir(nodekb)) throw new Error(`库目录不存在: ${nodekb}（注册表 ${name} 指向 ${entry.path}）`)
+      return { name, base: entry.path, nodekb, origin: entry.registry }
+    }
+    const discovered = discoverLibraries(ws).find((r) => r.name === name)
+    if (discovered) {
+      return { name, base: path.dirname(discovered.nodekb), nodekb: discovered.nodekb, origin: discovered.origin }
+    }
+    if (name === DEFAULT_KB) {
+      const wsLib = workspaceBase(ws)
+      if (wsLib) return wsLib
+    }
+    const names = [...registries.keys(), ...discoverLibraries(ws).map((r) => r.name)]
+    throw new Error(`未注册的库: ${name}（可用: ${names.join(', ') || '无'}；或用 lib 参数给绝对路径）`)
+  }
+
+  // 3) 无参：工作区自带 → 工作区里唯一发现 → 唯一的注册表库
+  const wsLib = workspaceBase(ws)
+  if (wsLib) return wsLib
+  const found = discoverLibraries(ws)
+  if (found.length === 1) {
+    return { name: found[0].name, base: path.dirname(found[0].nodekb), nodekb: found[0].nodekb, origin: found[0].origin }
+  }
+  if (found.length > 1) {
+    throw new Error(
+      `未指定库（工作区根没有 .nodekb，但发现 ${found.length} 个）：${found.map((r) => r.name).join('、')}\n` +
+        `用 kb 参数选一个，或把库放到工作区根的 .nodekb。`,
+    )
+  }
+  if (registries.size === 1) {
+    const [[only, entry]] = [...registries.entries()]
+    const nodekb = path.join(entry.path, '.nodekb')
+    if (isDir(nodekb)) return { name: only, base: entry.path, nodekb, origin: entry.registry }
+  }
+  if (registries.size > 1) {
+    throw new Error(
+      `未指定库（工作区没有 .nodekb）。已注册: ${[...registries.keys()].join(', ')}；用 kb 参数选一个。`,
+    )
+  }
+  throw new Error(
+    `没有可用库：工作区 ${ws} 下没有 .nodekb，注册表里也没有库。\n` +
+      `在项目里建 .nodekb/ 并放 md 文件即可（folder/文件/## 标题都会自动变成节点）；` +
+      `技能自带的知识库放在 .dsh/skills/<技能名>/.nodekb/ 也会被自动发现。`,
+  )
+}
+
+/** 列出可用库（不解析内容，避免一次拖动整库） */
+export function listLibraries({ workspace, config } = {}) {
+  const ws = path.resolve(workspace || process.cwd())
+  const registries = loadRegistries(
+    config && config.registries ? config.registries : defaultRegistryPaths(ws),
+    config && config.libraries,
+  )
+  const rows = []
+  const seen = new Set()
+  for (const r of discoverLibraries(ws)) {
+    rows.push({ name: r.name, path: path.dirname(r.nodekb), exists: true, origin: r.origin })
+    seen.add(r.nodekb)
+  }
+  for (const [name, entry] of registries) {
+    const nodekb = path.join(entry.path, '.nodekb')
+    if (seen.has(nodekb)) continue
+    rows.push({ name, path: entry.path, exists: isDir(nodekb), origin: entry.registry })
+  }
+  return rows
+}

package/lib/engine/rename.js

@@ -0,0 +1,203 @@
+/**
+ * rename —— 改文件节点名并把 [[TID]] 引用一起搬走。
+ *
+ * 为什么需要它：nodekb 的 TID 由「文件夹 TID + 文件名 slug」派生，
+ * 所以重命名一个 md 会让它的 TID 变掉，散落各处的 `[[doc:03-x]]` 立刻变成悬空引用。
+ * 手工改名的代价是事后跑 kb_diag 再逐个 grep，所以把「改名 + 重写引用」做成一个原子动作。
+ *
+ * 三条纪律（抄 dsh-tiddlywiki 的教训）：
+ * 1. 写前重读：算好新内容后再 stat 一次，mtime/size 变了就跳过并报出来，绝不覆盖别人刚改的东西。
+ * 2. 围栏内的 `[[...]]` 不重写（parser 也不把它当引用，改了反而破坏示例代码）。
+ * 3. 只改 TID 这一层：`[[old]]` 与 `[[old:1.2]]` 都搬，`[[oldx]]` 这种前缀相同的别动。
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { slugify } from './parse.js'
+import { ROOT_TID } from './mdlib.js'
+
+const FENCE = '```'
+
+/** 把一段文本里的 oldTid 引用改写成 newTid（含 `oldTid:…` 子节点引用）。 */
+export function rewriteRefsInText(text, oldTid, newTid) {
+  const lines = String(text).split('\n')
+  const out = []
+  let count = 0
+  let fenced = false
+  for (const line of lines) {
+    if (line.trim().startsWith(FENCE)) {
+      fenced = !fenced
+      out.push(line)
+      continue
+    }
+    if (fenced) {
+      out.push(line)
+      continue
+    }
+    out.push(
+      line.replace(/\[\[([^[\]]+)\]\]/g, (whole, inner) => {
+        if (inner === oldTid) {
+          count += 1
+          return `[[${newTid}]]`
+        }
+        if (inner.startsWith(oldTid + ':')) {
+          count += 1
+          return `[[${newTid}${inner.slice(oldTid.length)}]]`
+        }
+        return whole
+      }),
+    )
+  }
+  return { text: out.join('\n'), count }
+}
+
+function absOf(lib, node) {
+  // source 是「绝对路径#L1-L22」（相对路径只在库根被移走时才可能出现）
+  const raw = String(node.source || '').split('#')[0]
+  if (!raw) return ''
+  return path.isAbsolute(raw) ? path.normalize(raw) : path.join(lib.nodekb, raw)
+}
+
+function relOf(lib, abs) {
+  return path.relative(lib.nodekb, abs).split(path.sep).join('/')
+}
+
+/** 收集库里所有 md（跳过点目录，与 parse_library 一致） */
+function allMarkdown(nodekb) {
+  const out = []
+  const walk = (d) => {
+    let entries
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue
+      const p = path.join(d, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (e.name.endsWith('.md')) out.push(p)
+    }
+  }
+  walk(nodekb)
+  return out
+}
+
+/**
+ * 重命名一个文件节点，并把它引用的 TID 搬过去。
+ * @param {{nodekb:string, nodes:Map}} lib openLibrary 的结果
+ * @param {string} target 文件节点 TID，或相对路径 `doc/03-x.md`
+ * @param {string} newName 新文件名（.md 可省略）
+ * @param {{dryRun?:boolean}} [opts]
+ */
+export function renameFileNode(lib, target, newName, opts = {}) {
+  const nodes = lib.nodes
+  const wanted = String(target || '').trim()
+  if (!wanted) throw new Error('target 不能为空')
+
+  let node = nodes.get(wanted)
+  if (!node) {
+    // 允许直接给相对路径
+    const rel = wanted.split(path.sep).join('/')
+    node = [...nodes.values()].find((n) => n.kind === 'file' && String(n.source).split('#')[0] === rel)
+  }
+  if (!node) throw new Error(`未找到节点: ${wanted}（可先 kb_read --toc 看 TID 清单）`)
+  if (node.kind !== 'file') {
+    throw new Error(`只能重命名文件节点；${node.tid} 是 ${node.kind} 节点（目录改名请直接改文件夹）`)
+  }
+
+  const from = absOf(lib, node)
+  if (!fs.existsSync(from)) throw new Error(`源文件不存在: ${relOf(lib, from)}`)
+
+  let name = String(newName || '').trim()
+  if (!name) throw new Error('new_name 不能为空')
+  if (!name.endsWith('.md')) name += '.md'
+  const to = path.join(path.dirname(from), name)
+  if (path.resolve(to) === path.resolve(from)) throw new Error('新旧文件名相同，没有要改的')
+  if (fs.existsSync(to)) throw new Error(`目标已存在: ${relOf(lib, to)}`)
+
+  const stem = name.replace(/\.md$/, '')
+  const parent = node.parent_tid || ROOT_TID
+  const newTid = parent === ROOT_TID ? slugify(stem) : `${parent}:${slugify(stem)}`
+  if (newTid === node.tid) {
+    throw new Error(`新文件名 slug 化后与旧 TID 相同（${newTid}），引用无需改动；只改大小写等请直接改文件`)
+  }
+
+  const report = {
+    from: relOf(lib, from),
+    to: relOf(lib, to),
+    tid: node.tid,
+    new_tid: newTid,
+    dry_run: Boolean(opts.dryRun),
+    rewritten: [],
+    skipped: [],
+  }
+
+  // 先算出要改哪些文件（读 → 重写），最后才动文件系统
+  const edits = []
+  for (const file of allMarkdown(lib.nodekb)) {
+    let text
+    let st1
+    try {
+      st1 = fs.statSync(file)
+      text = fs.readFileSync(file, 'utf8')
+    } catch (e) {
+      report.skipped.push({ path: relOf(lib, file), why: `读失败: ${e.message}` })
+      continue
+    }
+    if (!text.includes(oldRefPrefix(node.tid))) continue
+    const { text: next, count } = rewriteRefsInText(text, node.tid, newTid)
+    if (!count) continue
+    edits.push({ file, st1, next, count })
+  }
+
+  if (opts.dryRun) {
+    for (const e of edits) report.rewritten.push({ path: relOf(lib, e.file), count: e.count })
+    return report
+  }
+
+  fs.renameSync(from, to)
+  report.renamed = true
+
+  for (const e of edits) {
+    const target2 = e.file === from ? to : e.file
+    try {
+      const st2 = fs.statSync(target2)
+      if (st2.mtimeMs !== e.st1.mtimeMs || st2.size !== e.st1.size) {
+        report.skipped.push({ path: relOf(lib, target2), why: '读后被改动，未覆盖' })
+        continue
+      }
+      fs.writeFileSync(target2, e.next, 'utf8')
+      report.rewritten.push({ path: relOf(lib, target2), count: e.count })
+    } catch (err) {
+      report.skipped.push({ path: relOf(lib, target2), why: err.message })
+    }
+  }
+
+  return report
+}
+
+function oldRefPrefix(tid) {
+  return `[[${tid}`
+}
+
+/** 人读的回执 */
+export function formatRename(report) {
+  const lines = []
+  const head = report.dry_run ? '（演练，未落盘）' : ''
+  lines.push(`${head}已重命名「${report.from}」→「${report.to}」`)
+  lines.push(`TID: ${report.tid} → ${report.new_tid}`)
+  if (report.rewritten.length) {
+    const total = report.rewritten.reduce((s, r) => s + r.count, 0)
+    lines.push(`更新了 ${total} 处引用（${report.rewritten.length} 个文件）`)
+    for (const r of report.rewritten.slice(0, 10)) lines.push(`  - ${r.path}: ${r.count}`)
+    if (report.rewritten.length > 10) lines.push(`  …另有 ${report.rewritten.length - 10} 个文件`)
+  } else {
+    lines.push('没有需要改写的引用')
+  }
+  if (report.skipped.length) {
+    lines.push(`跳过 ${report.skipped.length} 个文件（未覆盖）：`)
+    for (const s of report.skipped.slice(0, 10)) lines.push(`  - ${s.path}: ${s.why}`)
+  }
+  return lines.join('\n')
+}

package/lib/engine/render.js

@@ -0,0 +1,138 @@
+/**
+ * render —— 基于内存节点模型的渲染层（md 即库，无持久化状态）。
+ *
+ * - render_node / render_subtree：[[TID]] 就地填充（transclusion 展开）
+ * - toc_lines：目录视图（tid · 标题 · 字符数，不渲染正文）
+ * - node_info：节点元信息（含 source 行号）
+ * - 环检测：展开路径重复出现同一 TID 抛 TransclusionError；悬空引用保留 [[TID]] 原文
+ */
+
+import { refRegex } from './parse.js'
+
+export class TransclusionError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'TransclusionError'
+  }
+}
+
+function children(nodes, tid) {
+  const out = []
+  for (const n of nodes.values()) if (n.parent_tid === tid) out.push(n)
+  out.sort((a, b) => (a.sort - b.sort) || (a.tid < b.tid ? -1 : a.tid > b.tid ? 1 : 0))
+  return out
+}
+
+function cycle_msg(seen, target, nodes) {
+  let msg = `循环引用: ${[...seen, target].join(' -> ')}`
+  const node = nodes.get(target)
+  if (node && node.source) msg += `（重复节点源: ${node.source}）`
+  return msg
+}
+
+/** 容器节点（文件夹/文件）转译：整支子树投影（`## 标题` + 内容 + 子节递归） */
+function project_container(nodes, tid, seen) {
+  const node = nodes.get(tid)
+  const parts = []
+  const title = node.title || tid
+  if (title !== tid) parts.push('## ' + title) // 显式节点（title===tid）内联时不输出标题，避免列表内噪音
+  parts.push(expand(node.content, nodes, seen))
+  for (const child of children(nodes, tid)) {
+    parts.push(project_container(nodes, child.tid, [...seen, child.tid]))
+  }
+  return parts.join('\n\n')
+}
+
+function expand(text, nodes, seen) {
+  const out = []
+  let pos = 0
+  for (const m of String(text).matchAll(refRegex())) {
+    out.push(text.slice(pos, m.index))
+    const target = m[1]
+    if (seen.includes(target)) throw new TransclusionError(cycle_msg(seen, target, nodes))
+    const nxt = [...seen, target]
+    const node = nodes.get(target)
+    if (node) {
+      // 仅 文件夹/文件 容器展开整支子树；显式 <node> 原子引用只展开自身（避免同文件兄弟被连带展开）
+      if (node.kind === 'folder' || node.kind === 'file') out.push(project_container(nodes, target, nxt))
+      else out.push(expand(node.content, nodes, nxt))
+    } else {
+      out.push(m[0]) // 悬空：保留原文，diag 报告
+    }
+    pos = m.index + m[0].length
+  }
+  out.push(text.slice(pos))
+  return out.join('')
+}
+
+/** 渲染单节点内容（不含标题行） */
+export function render_node(nodes, tid) {
+  const node = nodes.get(tid)
+  if (!node) throw new Error(`节点不存在: ${tid}`)
+  return expand(node.content, nodes, [tid])
+}
+
+/** 渲染整支：递归子树为带标题层级的 md */
+export function render_subtree(nodes, tid, level = 1) {
+  const node = nodes.get(tid)
+  if (!node) throw new Error(`节点不存在: ${tid}`)
+  const title = node.title || tid
+  const head = '#'.repeat(level) + ' ' + title
+  const parts = [head, expand(node.content, nodes, [tid])]
+  for (const child of children(nodes, tid)) parts.push(render_subtree(nodes, child.tid, level + 1))
+  return parts.join('\n\n')
+}
+
+/** 目录视图：每节点一行（tid · 标题 · 字符数） */
+export function toc_lines(nodes, tid, level = 0) {
+  const node = nodes.get(tid)
+  if (!node) return [`未找到节点: ${tid}`]
+  const lines = [`${'  '.repeat(level)}- ${node.tid} · ${node.title || '(无标题)'} · ${node.content.length} 字符`]
+  for (const child of children(nodes, tid)) lines.push(...toc_lines(nodes, child.tid, level + 1))
+  return lines
+}
+
+/** 目录树（给 HTML 面板用，与 toc_lines 同源） */
+export function toc_tree(nodes, tid, depth = 0) {
+  const node = nodes.get(tid)
+  if (!node) return null
+  return {
+    tid: node.tid,
+    title: node.title || '',
+    type: node.type,
+    kind: node.kind,
+    positional: !!node.positional,
+    chars: node.content.length,
+    source: node.source,
+    children: children(nodes, tid).map((c) => toc_tree(nodes, c.tid, depth + 1)).filter(Boolean),
+  }
+}
+
+export function node_info(nodes, tid) {
+  const node = nodes.get(tid)
+  if (!node) throw new Error(`节点不存在: ${tid}`)
+  // 字段与 Python 版严格一致（kind/positional 由调用方按需补，避免 raw 输出漂移）
+  return {
+    tid: node.tid,
+    type: node.type,
+    title: node.title,
+    parent_tid: node.parent_tid,
+    sort: node.sort,
+    source: node.source,
+    content: node.content,
+  }
+}
+
+/** 路径解析（三级）：精确 TID → 段边界前缀唯一 → 裸前缀（模糊）唯一 */
+export function resolve_path(nodes, p) {
+  if (nodes.has(p)) return p
+  const keys = [...nodes.keys()]
+  let hits = keys.filter((t) => t === p || t.startsWith(p + ':')).sort()
+  if (hits.length === 1) return hits[0]
+  if (!hits.length) {
+    // 段边界无命中 → 裸前缀模糊（fact:mod → fact:modid / fact:modid-places / fact:modid-trap）
+    hits = keys.filter((t) => t.startsWith(p)).sort()
+    if (hits.length === 1) return hits[0]
+  }
+  return null
+}