dsh-obsidian-memo 0.16.3

package/lib/obsidian.js

@@ -0,0 +1,93 @@
+/**
+ * dsh-obsidian-memo —— 0.13.8「在 Obsidian 打开」的系统打开器（Host 半）。
+ *
+ * 为什么必须由 Host 打开：DSH 的外壳只把 http(s) 外链交给系统浏览器，
+ * `obsidian://` 这类自定义协议不会触发外部应用（浏览器半与 Electron 半都一样）。
+ * 所以 Client 只负责把便签路径发到 Host，Host 用系统命令打开 `obsidian://open?path=…`。
+ *
+ * 只依赖 node:child_process，零运行时依赖；测试可以用
+ * `setOpenExternalUrlForTests()` 覆盖真正的系统调用。
+ * @module dsh-obsidian-memo/obsidian
+ */
+
+import { execFile } from 'node:child_process'
+import { buildObsidianUri } from './shared.js'
+
+/** 系统打开器的等待上限（毫秒）；超时视为失败，避免 RPC 一直挂着。 */
+const OPEN_TIMEOUT_MS = 5000
+
+/** 测试注入点：每个测试文件是独立进程，模块级覆盖是安全的。 */
+let override = null
+
+/**
+ * 仅测试用：替换真正的系统打开调用；传 null 恢复。
+ * @param {((url: string) => Promise<{ ok: boolean, message?: string }>) | null} fn
+ */
+export function setOpenExternalUrlForTests(fn) {
+  override = typeof fn === 'function' ? fn : null
+}
+
+/**
+ * 各平台的「打开 URL」命令。argv 形式，不经过 shell，避免 URL 里的字符被解释。
+ * @param {string} url
+ * @param {string} [platform]
+ * @returns {{ command: string, args: string[] }}
+ */
+export function openUrlCommand(url, platform = process.platform) {
+  const target = String(url ?? '')
+  if (platform === 'darwin') return { command: 'open', args: [target] }
+  if (platform === 'win32') return { command: 'cmd', args: ['/c', 'start', '""', target] }
+  return { command: 'xdg-open', args: [target] }
+}
+
+/**
+ * 真正调用系统打开器；永远 resolve `{ ok, message? }`，不抛异常。
+ * @param {string} url
+ * @param {{ exec?: Function, platform?: string, timeoutMs?: number }} [options]
+ */
+export function systemOpenExternalUrl(url, options = {}) {
+  const exec = typeof options.exec === 'function' ? options.exec : execFile
+  const platform = typeof options.platform === 'string' && options.platform !== '' ? options.platform : process.platform
+  const timeoutMs = Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : OPEN_TIMEOUT_MS
+  const { command, args } = openUrlCommand(url, platform)
+  return new Promise((resolve) => {
+    let settled = false
+    const finish = (result) => {
+      if (settled) return
+      settled = true
+      resolve(result)
+    }
+    try {
+      exec(command, args, { timeout: timeoutMs, windowsHide: true }, (error) => {
+        if (error) finish({ ok: false, message: error?.message ?? String(error) })
+        else finish({ ok: true })
+      })
+    } catch (error) {
+      finish({ ok: false, message: error?.message ?? String(error) })
+    }
+  })
+}
+
+/**
+ * 打开一条外部 URL（当前只用于 obsidian://）。测试可覆盖。
+ * @param {string} url
+ * @returns {Promise<{ ok: boolean, message?: string }>}
+ */
+export async function openExternalUrl(url) {
+  const target = typeof url === 'string' ? url.trim() : ''
+  if (target === '') return { ok: false, message: '缺少要打开的链接' }
+  if (override) return override(target)
+  return systemOpenExternalUrl(target)
+}
+
+/**
+ * 打开一篇便签：把绝对路径转成 obsidian:// URI 后交给系统。
+ * @param {string} absPath
+ * @returns {Promise<{ ok: boolean, message?: string, url?: string }>}
+ */
+export async function openNoteInObsidian(absPath) {
+  const url = buildObsidianUri(absPath)
+  if (url === '') return { ok: false, message: '缺少便签路径' }
+  const opened = await openExternalUrl(url)
+  return Object.assign({ url }, opened)
+}

package/lib/scan.js

@@ -0,0 +1,269 @@
+/**
+ * dsh-obsidian-memo —— 便签目录扫描与缓存。
+ *
+ * 轮询式刷新（Obsidian 保存后数秒内反映），不注册文件监听、不占用文件锁。
+ * 每次 scan 只 stat 文件；内容仅在 mtime/size 变化时重读重解析。
+ * @module dsh-obsidian-memo/scan
+ */
+
+import { createHash } from 'node:crypto'
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { join, relative, sep } from 'node:path'
+import { LIMITS, colorForTag, darkColorForTag } from './shared.js'
+import { assertPathWithin, contentRevision, readNoteFile } from './files.js'
+import {
+  clip, commentKindsFrom, getBody, parseNote, summarizeImages, tagForRelativePath,
+} from './notes.js'
+
+const SKIP_DIRS = new Set(['node_modules', '__MACOSX', '.trash', '.obsidian'])
+const UNCONFIGURED = 'unconfigured'
+// 全文只为当前阅读服务；不要为整库长期保留正文、blocks 和全部评论。
+const FULL_CACHE_LIMIT = 4
+
+function fileSignature(info) {
+  return `${info.size}:${info.mtimeMs}:${info.ctimeMs}:${info.ino}:${info.birthtimeMs}`
+}
+
+/** 是否是可以进入的目录项。 */
+function walkable(dirent) {
+  if (!dirent.isDirectory()) return false
+  if (dirent.name.startsWith('.')) return false
+  if (SKIP_DIRS.has(dirent.name)) return false
+  return true
+}
+
+/**
+ * 收集 md 文件（跳过符号链接、隐藏目录）。
+ * @param {string} root - 当前目录。
+ * @param {number} depth - 当前深度（notesDir 顶层为 0）。
+ * @param {string[]} output - 收集结果。
+ * @param {boolean} [recursive] - false 时只看顶层，不进入子文件夹。
+ */
+async function collectMarkdown(root, depth, output, recursive = true) {
+  let entries
+  try {
+    entries = await readdir(root, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const dirent of entries) {
+    if (dirent.isSymbolicLink()) continue
+    const absolute = join(root, dirent.name)
+    if (dirent.isDirectory()) {
+      if (!recursive || depth >= LIMITS.maxDepth || !walkable(dirent)) continue
+      await collectMarkdown(absolute, depth + 1, output, recursive)
+      continue
+    }
+    if (!dirent.isFile()) continue
+    if (dirent.name.startsWith('.')) continue
+    if (!dirent.name.toLowerCase().endsWith('.md')) continue
+    output.push(absolute)
+  }
+}
+
+/** 一条便签的缓存记录。 */
+function buildSummary(entry, parsed) {
+  return {
+    path: entry.path,
+    relPath: entry.relPath,
+    name: entry.name,
+    title: entry.name,
+    excerpt: parsed.excerpt,
+    tag: entry.tag,
+    color: entry.color,
+    darkColor: entry.darkColor,
+    comments: parsed.comments.slice(0, LIMITS.summaryComments).map((comment) => ({
+      type: comment.type,
+      emoji: comment.emoji,
+      label: comment.label,
+      title: comment.title,
+      time: comment.time,
+      text: clip(comment.text, 500),
+    })),
+    commentCount: parsed.comments.length,
+    ...summarizeImages(parsed.blocks),
+    commentKinds: commentKindsFrom(parsed.comments),
+    created: entry.created,
+    mtime: entry.mtime,
+    size: entry.size,
+  }
+}
+
+export class NotesScanner {
+  constructor() {
+    /** @type {Map<string, object>} */
+    this.entries = new Map()
+    this.fullNotes = new Map()
+    this.revision = UNCONFIGURED
+    this.scanKey = ''
+  }
+
+  /** 清空全部缓存（设置变化时）。 */
+  reset() {
+    this.entries.clear()
+    this.fullNotes.clear()
+    this.revision = UNCONFIGURED
+    this.scanKey = ''
+  }
+
+  /** 丢弃单个文件的缓存（写入后）。 */
+  invalidate(filePath) {
+    this.entries.delete(filePath)
+    this.fullNotes.delete(filePath)
+  }
+
+  /**
+   * 扫描一次。
+   * @param {{ vaultPath: string, notesDir: string }} settings
+   * @returns {Promise<{ configured: boolean, error: string | null, revision: string, notes: object[] }>}
+   */
+  async scan(settings) {
+    const notesDir = settings?.notesDir ?? ''
+    const vaultPath = settings?.vaultPath ?? ''
+    const includeSubfolders = settings?.includeSubfolders !== false
+    if (!notesDir || !vaultPath) {
+      this.reset()
+      return { configured: false, error: null, revision: UNCONFIGURED, notes: [] }
+    }
+    // 扫描参数（仓库 / 目录 / 是否递归）任一变化都要清缓存，避免沿用旧的 tag 与摘要。
+    const scanKey = `${vaultPath}\u0000${notesDir}\u0000${includeSubfolders ? '1' : '0'}`
+    if (this.scanKey !== scanKey) {
+      this.entries.clear()
+      this.fullNotes.clear()
+      this.scanKey = scanKey
+    }
+    try {
+      await assertPathWithin(vaultPath, notesDir)
+      const info = await stat(notesDir)
+      if (!info.isDirectory()) {
+        return { configured: false, error: `便签目录不是文件夹：${notesDir}`, revision: UNCONFIGURED, notes: [] }
+      }
+    } catch (error) {
+      return {
+        configured: false,
+        error: `读不到便签目录：${notesDir}（${error?.cause?.code ?? error?.code ?? error?.message ?? '未知错误'}）`,
+        revision: UNCONFIGURED,
+        notes: [],
+      }
+    }
+
+    const files = []
+    await collectMarkdown(notesDir, 0, files, includeSubfolders)
+    const seen = new Set()
+    const signature = []
+    const notes = []
+
+    for (const absolute of files) {
+      let info
+      try {
+        info = await stat(absolute)
+      } catch {
+        continue
+      }
+      if (!info.isFile() || info.size > LIMITS.maxFileBytes) continue
+      const relPath = relative(vaultPath, absolute).split(sep).join('/')
+      const relativeToNotes = relative(notesDir, absolute).split(sep).join('/')
+      const fingerprint = fileSignature(info)
+
+      let entry = this.entries.get(absolute)
+      if (
+        entry !== undefined
+        && entry.fingerprint === fingerprint
+        && entry.scanKey === this.scanKey
+      ) {
+        seen.add(absolute)
+        notes.push(entry.summary)
+        signature.push(`${relativeToNotes}:${fingerprint}`)
+        continue
+      }
+      this.fullNotes.delete(absolute)
+      let text
+      try {
+        text = await readFile(absolute, 'utf8')
+      } catch {
+        continue
+      }
+      // 解析到 scanComments 条，保证 commentKinds 覆盖「全部评论」；summary 只取前 6 条。
+      const parsed = parseNote(text, { maxComments: LIMITS.scanComments, maxBlocks: LIMITS.blocks })
+      const tag = tagForRelativePath(relativeToNotes)
+      entry = {
+        path: absolute,
+        relPath,
+        name: relativeToNotes.split('/').pop().replace(/\.md$/i, ''),
+        tag,
+        color: colorForTag(tag),
+        darkColor: darkColorForTag(tag),
+        created: Math.round(info.birthtimeMs || info.ctimeMs || info.mtimeMs),
+        mtime: info.mtimeMs,
+        size: info.size,
+        scanKey: this.scanKey,
+        fingerprint,
+        summary: null,
+      }
+      entry.summary = buildSummary(entry, parsed)
+      seen.add(absolute)
+      this.entries.set(absolute, entry)
+      notes.push(entry.summary)
+      signature.push(`${relativeToNotes}:${fingerprint}`)
+    }
+
+    for (const key of [...this.entries.keys()]) {
+      if (!seen.has(key)) {
+        this.entries.delete(key)
+        this.fullNotes.delete(key)
+      }
+    }
+
+    // 默认按创建时间（新 → 旧）；其余排序由面板切换。
+    notes.sort((a, b) => (b.created - a.created) || a.relPath.localeCompare(b.relPath))
+    signature.sort()
+    this.revision = createHash('sha1')
+      .update(`${notesDir}\u0000${signature.join('\u0001')}`)
+      .digest('hex')
+      .slice(0, 16)
+
+    return { configured: true, error: null, revision: this.revision, notes }
+  }
+
+  /**
+   * 读取一张便签的全文（阅读视图用）。
+   * @param {string} filePath - md 绝对路径（调用方负责校验在 notesDir 内）。
+   * @returns {Promise<object | null>}
+   */
+  async readFull(filePath) {
+    const entry = this.entries.get(filePath)
+    if (entry === undefined) return null
+    const cached = this.fullNotes.get(filePath)
+    if (cached) {
+      this.fullNotes.delete(filePath)
+      this.fullNotes.set(filePath, cached)
+      return cached
+    }
+    const text = await readNoteFile(filePath)
+    const parsed = parseNote(text, { maxComments: LIMITS.scanComments, maxBlocks: LIMITS.blocks })
+    const full = {
+      ...entry.summary,
+      body: getBody(text),
+      contentRevision: contentRevision(text),
+      blocks: parsed.blocks,
+      comments: parsed.comments.slice(0, LIMITS.fullComments),
+      projects: parsed.projects,
+    }
+    // 读取期间可能发生 invalidate/reset；旧快照不重新进入缓存。
+    if (this.entries.get(filePath) === entry) {
+      this.fullNotes.set(filePath, full)
+      if (this.fullNotes.size > FULL_CACHE_LIMIT) this.fullNotes.delete(this.fullNotes.keys().next().value)
+    }
+    return full
+  }
+
+  /** 单个文件的当前缓存摘要（写入后使用）。 */
+  summary(filePath) {
+    return this.entries.get(filePath)?.summary ?? null
+  }
+
+  /** 一段 JSON 指纹，用于 jobs 参与 revision。 */
+  static hash(value) {
+    return createHash('sha1').update(String(value)).digest('hex').slice(0, 16)
+  }
+}

package/lib/settings.js

@@ -0,0 +1,228 @@
+/**
+ * dsh-obsidian-memo —— 设置：默认值、规范化、读写。
+ *
+ * 设置迁移自插件旧的 `data/settings.json`，运行时存于独立用户配置目录。
+ * `Config` 只为首启提供默认值；面板与官方设置页共用 JSON 文件。
+ * @module dsh-obsidian-memo/settings
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, basename, isAbsolute, normalize, resolve, join, relative } from 'node:path'
+import {
+  CALLOUT_TYPES, DEFAULT_AI, DEFAULT_EMOJIS, DEFAULT_PROJECT_PROMPT, FALLBACK_CALLOUT, LIMITS,
+  isLegacyDefaultEmojis, isPlainObject, normalizeAi, normalizeImageCompression, DEFAULT_IMAGE_COMPRESSION,
+} from './shared.js'
+import { atomicWrite } from './files.js'
+
+/** 首次运行时的设置。 */
+export const DEFAULT_SETTINGS = {
+  vaultPath: '',
+  notesDir: '',
+  projectDir: '',
+  attachmentDir: '',
+  archiveTargets: [],
+  folderHistory: [],
+  // 0.13：每枚 emoji 带一份 AI 预算（默认高：high / 8192 tokens）。
+  emojis: DEFAULT_EMOJIS.map((item) => ({ ...item, ai: { ...DEFAULT_AI } })),
+  projectPrompt: DEFAULT_PROJECT_PROMPT,
+  // 0.13：开档（结构化项目文档）自己的一份 AI 预算，默认同为高。
+  projectAi: { ...DEFAULT_AI },
+  // 0.13：是否扫描便签目录的子文件夹；缺省/非 false 一律 true。
+  includeSubfolders: true,
+  imageCompression: { ...DEFAULT_IMAGE_COMPRESSION },
+}
+
+/** 生成稳定 id（用于 emoji / 归档目录）。 */
+export function makeId(prefix = 'id') {
+  return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`
+}
+
+/** 单行字符串：去空白、去 NUL。 */
+function text(value, fallback = '') {
+  if (typeof value !== 'string') return fallback
+  return value.replace(/\u0000/g, '').trim() || fallback
+}
+
+/** 路径规范化：绝对路径原样归一；相对路径相对 vault 解析；空串保留。 */
+export function resolveUserPath(value, vaultPath) {
+  let raw = text(value)
+  if (raw === '') return ''
+  if (raw === '~') raw = homedir()
+  else if (raw.startsWith('~/')) raw = resolve(homedir(), raw.slice(2))
+  if (isAbsolute(raw)) return normalize(raw)
+  if (vaultPath) return resolve(vaultPath, raw)
+  return raw
+}
+
+/** 一个归档目标。 */
+function normalizeTarget(raw, index) {
+  if (!isPlainObject(raw)) return null
+  const path = text(raw.path)
+  if (!path) return null
+  const label = text(raw.label) || basename(path) || `归档 ${index + 1}`
+  const id = text(raw.id) || makeId('archive')
+  return { id, label, path }
+}
+
+/** 一条 emoji 定义。 */
+function normalizeEmoji(raw, index) {
+  if (!isPlainObject(raw)) return null
+  const emoji = text(raw.emoji)
+  if (!emoji) return null
+  const label = text(raw.label) || `评论 ${index + 1}`
+  const callout = CALLOUT_TYPES.includes(raw.callout) ? raw.callout : FALLBACK_CALLOUT
+  const prompt = text(raw.prompt) || DEFAULT_EMOJIS[0].prompt
+  return {
+    id: text(raw.id) || makeId('emoji'),
+    emoji: emoji.slice(0, 16),
+    label: label.slice(0, 24),
+    callout,
+    prompt,
+    // 0.13：这枚 emoji 生成评论时的 token 预算；旧设置文件没有该字段时补默认高。
+    ai: normalizeAi(raw.ai),
+  }
+}
+
+/**
+ * 把任意来源的设置规范化为安全、完整的形状。
+ * 非法字段回退默认值；路径解析为绝对路径（相对 vault）；去重。
+ * @param {unknown} raw - data/settings.json 或 RPC 传入的设置。
+ * @param {{ vaultPath?: string }} [options] - 已知仓库路径（normalize 时作为相对基准）。
+ * @returns {typeof DEFAULT_SETTINGS}
+ */
+export function normalizeSettings(raw, options = {}) {
+  const source = isPlainObject(raw) ? raw : {}
+  const vaultPath = resolveUserPath(source.vaultPath ?? DEFAULT_SETTINGS.vaultPath, options.vaultPath ?? '')
+  const notesDir = resolveUserPath(source.notesDir ?? '', vaultPath)
+  const projectDir = resolveUserPath(source.projectDir ?? '', vaultPath)
+  const attachmentDir = resolveUserPath(source.attachmentDir ?? '', vaultPath)
+  const projectPrompt = text(source.projectPrompt, '') || DEFAULT_PROJECT_PROMPT
+
+  const archiveTargets = []
+  const seenPaths = new Set()
+  const rawTargets = Array.isArray(source.archiveTargets) ? source.archiveTargets : []
+  for (const item of rawTargets.slice(0, 24)) {
+    const target = normalizeTarget(item, archiveTargets.length)
+    if (!target) continue
+    target.path = resolveUserPath(target.path, vaultPath)
+    if (seenPaths.has(target.path)) continue
+    seenPaths.add(target.path)
+    archiveTargets.push(target)
+  }
+
+  const emojis = []
+  const seenIds = new Set()
+  const rawEmojis = Array.isArray(source.emojis) ? source.emojis : DEFAULT_EMOJIS
+  for (const item of rawEmojis.slice(0, LIMITS.emojis)) {
+    const emoji = normalizeEmoji(item, emojis.length)
+    if (!emoji) continue
+    if (seenIds.has(emoji.id)) emoji.id = makeId('emoji')
+    seenIds.add(emoji.id)
+    emojis.push(emoji)
+  }
+
+  return {
+    vaultPath,
+    notesDir,
+    projectDir,
+    attachmentDir,
+    archiveTargets,
+    folderHistory: [...new Set([
+      notesDir, projectDir, attachmentDir, ...archiveTargets.map((item) => item.path),
+      ...(Array.isArray(source.folderHistory) ? source.folderHistory.filter((item) => typeof item === 'string').map((item) => resolveUserPath(item, vaultPath)) : []),
+    ].filter((item) => item && vaultPath && !relative(vaultPath, item).split(/[\\/]/).some((part) => part === '..' || part.startsWith('.')) && !isAbsolute(relative(vaultPath, item))))].slice(0, 40),
+    emojis: emojis.length > 0 ? emojis : DEFAULT_EMOJIS.map((item) => ({ ...item, ai: { ...DEFAULT_AI } })),
+    projectPrompt,
+    projectAi: normalizeAi(source.projectAi),
+    // 只有显式 false 才关闭；缺省、null、旧文件里没有这个字段都按 true 处理。
+    includeSubfolders: source.includeSubfolders !== false,
+    imageCompression: normalizeImageCompression(source.imageCompression),
+  }
+}
+
+/** 读取设置文件；不存在或损坏时返回默认值。 */
+export async function readSettingsFile(filePath, fallback = DEFAULT_SETTINGS) {
+  try {
+    const raw = await readFile(filePath, 'utf8')
+    const parsed = JSON.parse(raw)
+    // 0.13 预设迁移：旧版默认四枚（与 LEGACY_EMOJIS 逐字段一致）整组换成新默认值。
+    // 用户改过任何一项就原样保留；迁移只发生在内存里，下次 saveSettings 才落盘。
+    if (isPlainObject(parsed) && isLegacyDefaultEmojis(parsed.emojis)) {
+      parsed.emojis = DEFAULT_EMOJIS.map((item) => ({ ...item }))
+    }
+    return normalizeSettings(parsed, { vaultPath: fallback.vaultPath })
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error instanceof SyntaxError) return normalizeSettings(fallback)
+    throw error
+  }
+}
+
+/** 原子写入设置文件。 */
+export async function writeSettingsFile(filePath, settings) {
+  const normalized = normalizeSettings(settings)
+  await mkdir(dirname(filePath), { recursive: true })
+  await atomicWrite(filePath, `${JSON.stringify(normalized, null, 2)}\n`, { mode: 0o600 })
+  return normalized
+}
+
+/** 两个设置是否等价（用于决定是否重扫）。 */
+export function settingsEqual(a, b) {
+  return JSON.stringify(normalizeSettings(a)) === JSON.stringify(normalizeSettings(b))
+}
+
+/** npm 安装目录之外的用户配置；环境变量仍可显式覆盖。 */
+export function configHome(env = process.env, platform = process.platform, home = homedir()) {
+  const root = platform === 'win32' ? (env.APPDATA || join(home, 'AppData', 'Roaming'))
+    : (env.XDG_CONFIG_HOME || join(home, '.config'))
+  return join(root, 'dsh-obsidian-memo')
+}
+
+/** 文件内保存仓库相对路径，运行时继续使用绝对路径。 */
+export function portableSettings(settings) {
+  const value = normalizeSettings(settings)
+  const path = (item) => item && value.vaultPath && !isAbsolute(relative(value.vaultPath, item))
+    && !relative(value.vaultPath, item).split(/[\\/]/).includes('..') ? relative(value.vaultPath, item) || '.' : item
+  return { ...value, notesDir: path(value.notesDir), projectDir: path(value.projectDir), attachmentDir: path(value.attachmentDir),
+    archiveTargets: value.archiveTargets.map((item) => ({ ...item, path: path(item.path) })),
+    folderHistory: value.folderHistory.map(path) }
+}
+
+export async function readConfigFile(filePath) {
+  const parsed = JSON.parse(await readFile(filePath, 'utf8'))
+  if (!isPlainObject(parsed)) throw new Error('配置文件必须是 JSON 对象')
+  if (isLegacyDefaultEmojis(parsed.emojis)) parsed.emojis = DEFAULT_EMOJIS.map((item) => ({ ...item }))
+  return normalizeSettings(parsed)
+}
+
+export async function writeConfigFile(filePath, settings, { exclusive = false } = {}) {
+  await mkdir(dirname(filePath), { recursive: true })
+  const body = `${JSON.stringify(portableSettings(settings), null, 2)}\n`
+  if (exclusive) await writeFile(filePath, body, { flag: 'wx', mode: 0o600 })
+  else await atomicWrite(filePath, body, { mode: 0o600 })
+  return normalizeSettings(settings)
+}
+
+export async function locateConfig({ legacyPath, home = configHome(), override = process.env.DSH_STICKY_NOTES_SETTINGS } = {}) {
+  if (override) return { path: resolveUserPath(override), home, pinned: true }
+  try {
+    const pointer = JSON.parse(await readFile(join(home, 'location.json'), 'utf8'))
+    if (typeof pointer.path === 'string' && isAbsolute(pointer.path)) return { path: pointer.path, home, pinned: false }
+  } catch (error) { if (error.code !== 'ENOENT') throw error }
+  const path = join(home, 'config.json')
+  try { await readFile(path) } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+    if (legacyPath) {
+      try { await writeConfigFile(path, await readConfigFile(legacyPath), { exclusive: true }) }
+      catch (cause) { if (cause.code !== 'ENOENT' && cause.code !== 'EEXIST') throw cause }
+    }
+  }
+  return { path, home, pinned: false }
+}
+
+export async function rememberConfig(location, path) {
+  if (location.pinned) return
+  await mkdir(location.home, { recursive: true })
+  const target = join(location.home, 'location.json')
+  await atomicWrite(target, `${JSON.stringify({ path }, null, 2)}\n`, { mode: 0o600 })
+}