@chainlesschain/personal-data-hub 0.2.4 → 0.3.0

package/lib/adapters/vscode/vscode-reader.js

@@ -0,0 +1,191 @@
+"use strict";
+
+// vscode-reader — pulls workspace folders + terminal history out of VSCode's
+// own state files. Two on-disk sources, both desktop-local:
+//
+//   1. `%APPDATA%\Code\User\workspaceStorage\<hash>\workspace.json`
+//      Each `workspace.json` carries `{ folder: "file:///..." }` — the
+//      decoded URI is the project root the user opened. Folder mtime gives
+//      us a "last opened" timestamp (when VSCode last touched the storage).
+//
+//   2. `%APPDATA%\Code\User\globalStorage\state.vscdb` (plain SQLite)
+//      ItemTable contains JSON blobs keyed by `terminal.history.entries.*`.
+//      Single snapshot timestamp at `terminal.history.timestamp.*` — there
+//      is no per-command timestamp, only the "last updated" of the whole
+//      list. We anchor every command/dir to that timestamp.
+//
+// Like the Chromium readers, we copy the SQLite file first — VSCode keeps
+// state.vscdb open while running, and a direct read would fight WAL.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+// Dual-load: bs3mc tracks Electron's ABI 140 (runtime path), plain
+// better-sqlite3 tracks Node's ABI 127 (test path). Whichever loads
+// wins. See chrome-db-reader.js for the same pattern + rationale.
+function loadDatabase() {
+  for (const mod of ["better-sqlite3-multiple-ciphers", "better-sqlite3"]) {
+    let cls;
+    try {
+      // eslint-disable-next-line global-require
+      cls = require(mod);
+    } catch (_e) {
+      continue;
+    }
+    try {
+      const probe = new cls(":memory:");
+      probe.close();
+      return cls;
+    } catch (_e) {
+      /* ABI mismatch, try next */
+    }
+  }
+  throw new Error(
+    "vscode-reader: neither better-sqlite3-multiple-ciphers nor better-sqlite3 loaded — both ABI-mismatched",
+  );
+}
+const Database = loadDatabase();
+
+function defaultVscodeRoot() {
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA;
+    if (!appData) return null;
+    return path.join(appData, "Code");
+  }
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "Code");
+  }
+  return path.join(os.homedir(), ".config", "Code");
+}
+
+// Decode a file:// URI into a Windows / Posix path. Returns null when the
+// URI scheme isn't file:// (could be vscode-remote://, ssh://, etc — those
+// stay as URIs for the caller).
+function decodeFileUri(uri) {
+  if (typeof uri !== "string" || !uri.startsWith("file://")) return null;
+  // file:///c%3A/code/foo → /c:/code/foo → c:/code/foo on win32
+  let p = decodeURIComponent(uri.slice("file://".length));
+  if (process.platform === "win32") {
+    // Strip leading slash and normalise separators
+    if (p.startsWith("/")) p = p.slice(1);
+    return p.replace(/\//g, "\\");
+  }
+  return p;
+}
+
+function* readWorkspaces(vscodeRoot, opts = {}) {
+  const fsMod = opts.fs || fs;
+  const wsRoot = path.join(vscodeRoot, "User", "workspaceStorage");
+  if (!fsMod.existsSync(wsRoot)) return;
+  const sinceMs = Number.isInteger(opts.since) && opts.since > 0 ? opts.since : 0;
+  let hashes;
+  try {
+    hashes = fsMod.readdirSync(wsRoot);
+  } catch {
+    return;
+  }
+  for (const h of hashes) {
+    const wsFile = path.join(wsRoot, h, "workspace.json");
+    if (!fsMod.existsSync(wsFile)) continue;
+    let stat;
+    let body;
+    try {
+      stat = fsMod.statSync(wsFile);
+      body = JSON.parse(fsMod.readFileSync(wsFile, "utf-8"));
+    } catch {
+      continue;
+    }
+    const lastOpenedMs = Math.floor(stat.mtimeMs);
+    if (sinceMs > 0 && lastOpenedMs < sinceMs) continue;
+    const folderUri = typeof body?.folder === "string" ? body.folder : null;
+    const workspaceUri = typeof body?.workspace === "string" ? body.workspace : null;
+    if (!folderUri && !workspaceUri) continue;
+    yield {
+      hash: h,
+      folderUri,
+      workspaceUri,
+      folderPath: folderUri ? decodeFileUri(folderUri) : null,
+      lastOpenedMs,
+    };
+  }
+}
+
+// Read terminal command + dir history from state.vscdb. Returns
+// { commands: [...], dirs: [...], commandsTimestampMs, dirsTimestampMs }.
+// Each entry is { value, shellType, sourceIndex } — the index lets us
+// reconstruct order across syncs.
+function readTerminalHistory(vscodeRoot, opts = {}) {
+  const fsMod = opts.fs || fs;
+  const src = path.join(vscodeRoot, "User", "globalStorage", "state.vscdb");
+  if (!fsMod.existsSync(src)) {
+    return { commands: [], dirs: [], commandsTimestampMs: null, dirsTimestampMs: null };
+  }
+  const tmp = path.join(
+    os.tmpdir(),
+    `pdh-vscode-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.db`,
+  );
+  fsMod.copyFileSync(src, tmp);
+  // VSCode uses plain SQLite (not WAL by default for state.vscdb), but copy
+  // the WAL sidecar if it exists just in case.
+  for (const ext of ["-wal", "-shm"]) {
+    const w = src + ext;
+    if (fsMod.existsSync(w)) {
+      try {
+        fsMod.copyFileSync(w, tmp + ext);
+      } catch {}
+    }
+  }
+  try {
+    const db = new Database(tmp, { readonly: true });
+    const get = (k) => {
+      try {
+        const r = db.prepare("SELECT value FROM ItemTable WHERE key=?").get(k);
+        return r ? r.value : null;
+      } catch {
+        return null;
+      }
+    };
+    const parseEntries = (jsonStr) => {
+      if (!jsonStr) return [];
+      try {
+        const parsed = JSON.parse(jsonStr);
+        const arr = Array.isArray(parsed?.entries) ? parsed.entries : [];
+        return arr
+          .map((e, i) => ({
+            value: typeof e?.key === "string" ? e.key : "",
+            shellType: e?.value?.shellType || null,
+            sourceIndex: i,
+          }))
+          .filter((e) => e.value.length > 0);
+      } catch {
+        return [];
+      }
+    };
+    const parseTs = (raw) => {
+      if (!raw) return null;
+      const n = Number(raw);
+      return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+    };
+    const out = {
+      commands: parseEntries(get("terminal.history.entries.commands")),
+      dirs: parseEntries(get("terminal.history.entries.dirs")),
+      commandsTimestampMs: parseTs(get("terminal.history.timestamp.commands")),
+      dirsTimestampMs: parseTs(get("terminal.history.timestamp.dirs")),
+    };
+    db.close();
+    return out;
+  } finally {
+    for (const ext of ["", "-wal", "-shm"]) {
+      try {
+        fsMod.unlinkSync(tmp + ext);
+      } catch {}
+    }
+  }
+}
+
+module.exports = {
+  defaultVscodeRoot,
+  decodeFileUri,
+  readWorkspaces,
+  readTerminalHistory,
+};

package/lib/adapters/win-recent/adapter.js

@@ -0,0 +1,150 @@
+"use strict";
+
+// WinRecentAdapter — surfaces Windows' cross-application "recently opened"
+// shortcut list as an Event(OTHER) stream. Windows-only; gracefully fails
+// authenticate() on macOS/Linux.
+
+const path = require("node:path");
+
+const {
+  ENTITY_TYPES,
+  EVENT_SUBTYPES,
+  CAPTURED_BY,
+} = require("../../constants");
+
+const {
+  defaultRecentDir,
+  readRecent,
+} = require("./win-recent-reader");
+
+const NAME = "win-recent";
+const VERSION = "0.1.0";
+
+class WinRecentAdapter {
+  constructor(opts = {}) {
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = ["sync:win-recent-shortcuts"];
+    this.extractMode = "file-import";
+    this.rateLimits = { perDay: 96 };
+    this.dataDisclosure = {
+      fields: ["recent:name,mtimeMs,size,lnkPath"],
+      sensitivity: "high",
+      legalGate: false,
+      defaultInclude: { recent: true },
+    };
+    this._deps = {
+      fs: require("node:fs"),
+      defaultDir: defaultRecentDir,
+    };
+    this._dirOverride = typeof opts.recentDir === "string" ? opts.recentDir : null;
+  }
+
+  _resolveDir(opts) {
+    if (typeof opts?.recentDir === "string" && opts.recentDir.length > 0) {
+      return opts.recentDir;
+    }
+    if (this._dirOverride) return this._dirOverride;
+    return this._deps.defaultDir();
+  }
+
+  async authenticate(ctx = {}) {
+    const dir = this._resolveDir(ctx);
+    if (!dir) {
+      return {
+        ok: false,
+        reason: "PLATFORM_UNSUPPORTED",
+        message: "Windows Recent shortcuts only exist on win32; pass opts.recentDir to point at a directory on other platforms",
+      };
+    }
+    if (!this._deps.fs.existsSync(dir)) {
+      return {
+        ok: false,
+        reason: "RECENT_DIR_NOT_FOUND",
+        message: `no Recent dir at ${dir}`,
+      };
+    }
+    return { ok: true, mode: "file-import", recentDir: dir };
+  }
+
+  async healthCheck() {
+    const dir = this._resolveDir({});
+    return { ok: !!dir && this._deps.fs.existsSync(dir), lastChecked: Date.now() };
+  }
+
+  async *sync(opts = {}) {
+    const dir = this._resolveDir(opts);
+    if (!dir || !this._deps.fs.existsSync(dir)) {
+      throw new Error(`win-recent.sync: no Recent dir at ${dir || "?"} — set opts.recentDir`);
+    }
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const capturedAt = Date.now();
+    let emitted = 0;
+    for (const r of readRecent(dir, { fs: this._deps.fs, since: opts.since })) {
+      if (emitted >= limit) return;
+      yield {
+        kind: "recent-file",
+        // Path is unique within the device; mtime gets folded into the
+        // event id so re-opening the same target produces a new row.
+        originalId: `win-recent:${r.lnkPath}:${r.mtimeMs}`,
+        capturedAt,
+        payload: r,
+      };
+      emitted += 1;
+    }
+  }
+
+  normalize(raw) {
+    const ingestedAt = Date.now();
+    const source = (originalId) => ({
+      adapter: NAME,
+      adapterVersion: VERSION,
+      capturedAt: raw.capturedAt,
+      capturedBy: CAPTURED_BY.SQLITE,
+      originalId,
+    });
+
+    if (raw.kind === "recent-file") {
+      const p = raw.payload || {};
+      const name = typeof p.name === "string" && p.name.length > 0 ? p.name : "(无名)";
+      const event = {
+        id: `event-win-recent-${hashOriginal(raw.originalId)}`,
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.OTHER,
+        occurredAt: Number.isInteger(p.mtimeMs) ? p.mtimeMs : raw.capturedAt,
+        ingestedAt,
+        source: source(raw.originalId),
+        actor: "self",
+        content: {
+          title: `打开了 ${name.length > 70 ? name.substring(0, 70) + "…" : name}`,
+          text: name,
+        },
+        extra: {
+          kind: "recent-file",
+          targetName: name,
+          lnkPath: typeof p.lnkPath === "string" ? p.lnkPath : null,
+          lnkSize: Number.isInteger(p.size) ? p.size : null,
+          source: "win-recent",
+        },
+      };
+      return { events: [event], persons: [], places: [], items: [], topics: [] };
+    }
+
+    throw new Error(`win-recent.normalize: unknown raw.kind=${raw.kind}`);
+  }
+}
+
+function hashOriginal(s) {
+  let h = 5381;
+  const str = typeof s === "string" ? s : "";
+  for (let i = 0; i < str.length; i++) {
+    h = ((h << 5) + h + str.charCodeAt(i)) >>> 0;
+  }
+  return h.toString(36);
+}
+
+module.exports = {
+  WinRecentAdapter,
+  WIN_RECENT_NAME: NAME,
+  WIN_RECENT_VERSION: VERSION,
+};

package/lib/adapters/win-recent/index.js

@@ -0,0 +1,16 @@
+"use strict";
+
+const {
+  WinRecentAdapter,
+  WIN_RECENT_NAME,
+  WIN_RECENT_VERSION,
+} = require("./adapter");
+const reader = require("./win-recent-reader");
+
+module.exports = {
+  WinRecentAdapter,
+  WIN_RECENT_NAME,
+  WIN_RECENT_VERSION,
+  defaultRecentDir: reader.defaultRecentDir,
+  readRecent: reader.readRecent,
+};

package/lib/adapters/win-recent/win-recent-reader.js

@@ -0,0 +1,72 @@
+"use strict";
+
+// win-recent-reader — lists .lnk shortcuts in %APPDATA%\Microsoft\Windows\
+// \Recent\. Windows writes one .lnk per file/folder the user opens from
+// any app (Explorer, Word, etc), so this is effectively a cross-application
+// "what did I touch and when" timeline.
+//
+// v0.1 yields name + mtime only. Resolving the .lnk's actual target path
+// requires parsing the Shell Link binary format (MS-SHLLINK) or shelling
+// out to PowerShell COM — both deferred until we know users want it.
+//
+// AutomaticDestinations / CustomDestinations subdirectories hold Jump List
+// data in opaque .automaticDestinations-ms / .customDestinations-ms binary
+// blobs. Skipped for v0.1.
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const RECENT_REL_PATH = ["Microsoft", "Windows", "Recent"];
+const SKIP_SUBDIRS = new Set(["AutomaticDestinations", "CustomDestinations"]);
+
+function defaultRecentDir() {
+  if (process.platform !== "win32") return null;
+  const appData = process.env.APPDATA;
+  if (!appData) return null;
+  return path.join(appData, ...RECENT_REL_PATH);
+}
+
+// Yield one record per .lnk in the Recent dir. Records are sorted ascending
+// by mtime so the registry watermark advances monotonically across syncs.
+function* readRecent(recentDir, opts = {}) {
+  const fsMod = opts.fs || fs;
+  if (!fsMod.existsSync(recentDir)) return;
+  const sinceMs = Number.isInteger(opts.since) && opts.since > 0 ? opts.since : 0;
+  let entries;
+  try {
+    entries = fsMod.readdirSync(recentDir);
+  } catch {
+    return;
+  }
+  const recs = [];
+  for (const e of entries) {
+    if (SKIP_SUBDIRS.has(e)) continue;
+    if (!e.toLowerCase().endsWith(".lnk")) continue;
+    const full = path.join(recentDir, e);
+    let stat;
+    try {
+      stat = fsMod.statSync(full);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile()) continue;
+    const mtimeMs = Math.floor(stat.mtimeMs);
+    if (sinceMs > 0 && mtimeMs < sinceMs) continue;
+    const name = e.slice(0, e.length - 4); // strip .lnk
+    recs.push({
+      name,
+      mtimeMs,
+      size: stat.size,
+      lnkPath: full,
+    });
+  }
+  recs.sort((a, b) => a.mtimeMs - b.mtimeMs);
+  for (const r of recs) yield r;
+}
+
+module.exports = {
+  defaultRecentDir,
+  readRecent,
+  RECENT_REL_PATH,
+  SKIP_SUBDIRS,
+};