dsh-obsidian-notes 0.0.0-stage → 0.5.0

package/src/session-store.js

@@ -0,0 +1,146 @@
+/**
+ * 会话日志的带外维护（host 侧）。
+ *
+ * DSH 的持久化层**不提供**删除或保留接口 ——
+ * `dsh-session-persistence` README 原文：「无删除或保留接口——剪枝已存储会话
+ * 属于带外后端维护」。所以插件要支持「彻底删除会话」，只能在文件系统层面
+ * 复刻官方 jsonl 后端的目录布局：
+ *
+ *   $DSH_HOME/sessions/<projectKey(cwd)>/<encodeSegment(id)>/session.vN.jsonl.zstd
+ *
+ * 因此这里镜像了 `dsh-session-persistence-jsonl` 的两个纯函数：
+ *   - `encodeSegment`：id → 单个安全路径段（`.`/`..` 特判，其余非
+ *     `[A-Za-z0-9._-]` 字符转 `~XXXX`）；
+ *   - 项目目录名不进代码：删除按「扫描 sessions/* 下名为该段的目录」发现，
+ *     于是不必知道 `projectKey` 的有损规则，也能覆盖 `_no-cwd` 等分组。
+ *
+ * 同时清掉对应的投影缓存 `storages/session_projcache/sessions/<id>.json`，
+ * 否则重启后冷读缓存里仍会残留一条指向已删日志的记录。
+ */
+import { lstat, readdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { dshHome } from "./vault-store.js";
+
+/** 会话 id 的合法形态：官方 id 只由 `[A-Za-z0-9._-]` 组成。 */
+export const SESSION_ID_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
+
+/** 一次请求允许删除的会话数上限（父会话 + 子代理闭包远小于此）。 */
+export const SESSION_DELETE_LIMIT = 500;
+
+/**
+ * 镜像 `dsh-session-persistence-jsonl` 的 `encodeSegment`。
+ * @param raw - 待编码的非空字符串。
+ * @returns 可作为单个路径段的转义结果。
+ */
+export function encodeSegment(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error("cannot encode an empty path segment");
+  }
+  if (raw === ".") return "~002E";
+  if (raw === "..") return "~002E~002E";
+  let out = "";
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i);
+    const ch = String.fromCharCode(code);
+    if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) out += ch;
+    else out += `~${code.toString(16).toUpperCase().padStart(4, "0")}`;
+  }
+  return out;
+}
+
+/**
+ * 判断一个字符串是否是可安全删除的会话 id。
+ * @param id - 待校验的值。
+ * @returns 合法（且不是 `.` / `..`）时为 true。
+ */
+export function isValidSessionId(id) {
+  return typeof id === "string"
+    && SESSION_ID_PATTERN.test(id)
+    && id !== "."
+    && id !== "..";
+}
+
+/** 会话日志根目录：$DSH_HOME/sessions。 */
+export function sessionsRoot() {
+  return join(dshHome(), "sessions");
+}
+
+/** 某个会话的投影缓存文件路径。 */
+export function projectionCachePath(id) {
+  return join(dshHome(), "storages", "session_projcache", "sessions", `${encodeSegment(id)}.json`);
+}
+
+/**
+ * 定位一个会话 id 在磁盘上的全部会话目录。
+ * 官方目录名就是 `encodeSegment(id)`，所以按该段名扫描每个项目分组即可，
+ * 无需知道会话的 cwd，也无需知道 `projectKey` 的转义规则。
+ * @param id - 已校验的会话 id。
+ * @returns 扫描到的会话目录（通常 0 或 1 个）与本次使用的根目录。
+ */
+export async function findSessionDirs(id) {
+  const root = sessionsRoot();
+  const segment = encodeSegment(id);
+  let groups;
+  try {
+    groups = await readdir(root, { withFileTypes: true });
+  } catch {
+    return { root, dirs: [] };
+  }
+  const dirs = [];
+  for (const group of groups) {
+    if (!group.isDirectory()) continue;
+    const candidate = join(root, group.name, segment);
+    try {
+      const st = await lstat(candidate);
+      // 只删真实目录：符号链接一律跳过，避免借链接删到根目录之外。
+      if (st.isDirectory() && !st.isSymbolicLink()) dirs.push(candidate);
+    } catch {
+      // 该分组下没有这个会话，正常情况。
+    }
+  }
+  return { root, dirs };
+}
+
+/**
+ * 删除后校验：该会话在磁盘上是否真的什么都不剩。
+ *
+ * 删除接口只把「确实不存在了」的 id 报为成功，所以必须回读确认 —— 仅凭
+ * `rm` 没有抛错不足以证明删除彻底（权限、占用、只读挂载都可能让它静默留下）。
+ * @param id - 已校验的会话 id。
+ * @returns `present` 为是否存在残留，`reason` 指出残留种类。
+ */
+export async function sessionArtifactsPresent(id) {
+  const { dirs } = await findSessionDirs(id);
+  if (dirs.length > 0) return { present: true, reason: "session directory" };
+  try {
+    await lstat(projectionCachePath(id));
+    return { present: true, reason: "projection cache" };
+  } catch {
+    return { present: false, reason: null };
+  }
+}
+
+/**
+ * 彻底删除一个会话的磁盘痕迹：会话目录（含其中的 lock 与全部日志代）
+ * 加上它的投影缓存。调用方须再用 {@link sessionArtifactsPresent} 回读确认。
+ * @param id - 已校验的会话 id。
+ * @returns 删除结果（`{ root, dirs, cacheRemoved }`）；找不到不算错误。
+ */
+export async function purgeSession(id) {
+  const { root, dirs } = await findSessionDirs(id);
+  const removed = [];
+  for (const dir of dirs) {
+    await rm(dir, { recursive: true, force: true });
+    removed.push(dir);
+  }
+  const cache = projectionCachePath(id);
+  let cacheRemoved = false;
+  try {
+    await lstat(cache);
+    await rm(cache, { force: true });
+    cacheRemoved = true;
+  } catch {
+    // 缓存缺失属正常（该会话可能从未写入投影缓存）。
+  }
+  return { root, dirs: removed, cacheRemoved };
+}

package/src/vault-store.js

@@ -0,0 +1,141 @@
+/**
+ * Vault 根目录与附件行为的持久化管理（host 侧）：
+ * 设置文件位于 $DSH_HOME/dsh-obsidian-vault.json（DSH_HOME 缺省 ~/.dsh），
+ * 默认 Vault 根 = $DSH_WORKSPACE/obsidian_vault（DSH_WORKSPACE 缺省 process.cwd()）。
+ *
+ * 附件设置对齐 Obsidian「Files & Links」的两组**独立**选项：
+ *   · 位置（attachmentMode）：root（Vault 根）/ fixed（固定目录）/ note（与笔记同目录）
+ *     / sub（笔记目录下的子目录）
+ *   · 链接格式：固定用 Obsidian 默认的「shortest path when possible」，由 index.js
+ *     的 embedTargetFor 决定，**与位置设置解耦**（位置只管存哪里，链接只管怎么写）。
+ */
+import { readFile, writeFile, rename, mkdir, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+const SETTINGS_FILENAME = "dsh-obsidian-vault.json";
+
+/** 附件落盘位置模式（对应 Obsidian 的「Default location for new attachments」）。 */
+export const ATTACHMENT_MODES = new Set(["root", "fixed", "note", "sub"]);
+
+/** DSH 主目录：$DSH_HOME（缺省 ~/.dsh）。会话日志、投影缓存等都在其下。 */
+export function dshHome() {
+  return process.env.DSH_HOME && process.env.DSH_HOME.trim() !== ""
+    ? process.env.DSH_HOME
+    : join(homedir(), ".dsh");
+}
+
+export function settingsPath() {
+  return join(dshHome(), SETTINGS_FILENAME);
+}
+
+/** 默认 Vault 根：$DSH_WORKSPACE/obsidian_vault，缺省 process.cwd()/obsidian_vault。 */
+export function defaultVaultRoot() {
+  const ws = process.env.DSH_WORKSPACE;
+  if (ws && ws.trim() !== "") return join(ws, "obsidian_vault");
+  return join(process.cwd(), "obsidian_vault");
+}
+
+/**
+ * 读设置。缺省值刻意保持**向后兼容**：老设置文件只有 `attachmentDir`，此时按
+ * 「空 → Vault 根 / 非空 → 固定目录」还原出等价行为，既有用户语义不变。
+ */
+export async function readSettings() {
+  let data = {};
+  try {
+    const parsed = JSON.parse(await readFile(settingsPath(), "utf8"));
+    if (parsed && typeof parsed === "object") data = parsed;
+  } catch {
+    // 设置文件不存在或损坏：回到默认值。
+  }
+  const attachmentDir = typeof data.attachmentDir === "string" ? data.attachmentDir : "attachments";
+  const vaultRoot = typeof data.vaultRoot === "string" && data.vaultRoot.trim() !== "" ? data.vaultRoot : null;
+  return {
+    vaultRoot,
+    attachmentDir,
+    attachmentMode: typeof data.attachmentMode === "string" && ATTACHMENT_MODES.has(data.attachmentMode)
+      ? data.attachmentMode
+      : (attachmentDir === "" ? "root" : "fixed"),
+    attachmentSubfolder: typeof data.attachmentSubfolder === "string" && data.attachmentSubfolder.trim() !== ""
+      ? data.attachmentSubfolder.trim()
+      : "attachments",
+    // 目录树里隐藏附件目录（默认开；Obsidian 不隐藏，这里保留为可关闭的降噪选项）
+    hideAttachmentDir: data.hideAttachmentDir !== false,
+    // 保存笔记时自动删除孤儿附件（默认**关**：Obsidian 不自动删，误删不可恢复）
+    deleteOrphanAttachments: data.deleteOrphanAttachments === true,
+  };
+}
+
+export async function writeSettings(settings) {
+  const path = settingsPath();
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  await writeFile(tmp, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  await rename(tmp, path);
+}
+
+/** 合并式写入：只覆盖 patch 里出现的字段，其余保持当前值。 */
+export async function updateSettings(patch = {}) {
+  const cur = await readSettings();
+  const vaultRoot = patch.vaultRoot !== undefined ? patch.vaultRoot : cur.vaultRoot;
+  const next = {
+    ...(vaultRoot ? { vaultRoot } : {}),
+    attachmentDir: patch.attachmentDir !== undefined ? patch.attachmentDir : cur.attachmentDir,
+    attachmentMode: patch.attachmentMode !== undefined ? patch.attachmentMode : cur.attachmentMode,
+    attachmentSubfolder: patch.attachmentSubfolder !== undefined ? patch.attachmentSubfolder : cur.attachmentSubfolder,
+    hideAttachmentDir: patch.hideAttachmentDir !== undefined ? patch.hideAttachmentDir : cur.hideAttachmentDir,
+    deleteOrphanAttachments: patch.deleteOrphanAttachments !== undefined
+      ? patch.deleteOrphanAttachments
+      : cur.deleteOrphanAttachments,
+  };
+  await writeSettings(next);
+  return { ...next, vaultRoot: vaultRoot ?? null };
+}
+
+/**
+ * 设置固定附件目录（POSIX "/" 分隔；"" 表示 Vault 根）。
+ * 同时把位置模式切到 fixed / root —— 手填目录本身就表达了「用固定目录」。
+ */
+export async function setAttachmentDir(dir) {
+  const next = await updateSettings({ attachmentDir: dir, attachmentMode: dir === "" ? "root" : "fixed" });
+  return next.attachmentDir;
+}
+
+/**
+ * 解析当前生效的 Vault 根：优先用户配置，否则默认值。
+ * 返回 realpath（若目录存在）；目录不存在时返回 resolve 后的默认路径。
+ */
+export async function resolveVaultRoot() {
+  const settings = await readSettings();
+  const candidates = settings.vaultRoot ? [settings.vaultRoot] : [defaultVaultRoot()];
+  for (const candidate of candidates) {
+    if (!isAbsolute(candidate)) continue;
+    try {
+      const real = await realpath(candidate);
+      const st = await stat(real);
+      if (st.isDirectory()) return real;
+    } catch {
+      // 不存在或不可访问，继续尝试下一个候选。
+    }
+  }
+  return resolve(defaultVaultRoot());
+}
+
+/** 校验并保存用户选择的 Vault 根，返回 realpath。 */
+export async function setVaultRoot(input) {
+  if (typeof input !== "string" || input.trim() === "" || !isAbsolute(input)) {
+    throw Object.assign(new Error("vault root must be an absolute path"), { status: 400 });
+  }
+  let real;
+  try {
+    real = await realpath(input);
+  } catch {
+    throw Object.assign(new Error(`directory does not exist: ${input}`), { status: 400 });
+  }
+  const st = await stat(real);
+  if (!st.isDirectory()) {
+    throw Object.assign(new Error(`not a directory: ${input}`), { status: 400 });
+  }
+  const next = await updateSettings({ vaultRoot: real });
+  return next.vaultRoot ?? real;
+}