@chainlesschain/personal-data-hub 0.2.4 → 0.3.1

package/lib/adapters/vscode/adapter.js

@@ -0,0 +1,285 @@
+"use strict";
+
+// VSCodeAdapter — pulls VSCode workspace history + global terminal history
+// from on-disk state. Desktop-local, zero network, no extension required.
+//
+// Sources (all under `%APPDATA%\Code\` on Win, equivalent on macOS/Linux):
+//   - User/workspaceStorage/<hash>/workspace.json  → each opened project
+//   - User/globalStorage/state.vscdb               → terminal command history
+//
+// Yields:
+//   kind="workspace"        → Item(LINK, category="code-project")
+//   kind="terminal-command" → Event(OTHER, content.title=cmd[0..80])
+//   kind="terminal-dir"     → Event(OTHER, content.title=cd <dir>)
+//
+// Caveat: terminal history has NO per-entry timestamp in VSCode — only a
+// single "snapshot updated" ts. We anchor every command/dir to that ts and
+// add `sourceIndex` to extra so callers can reconstruct order. Re-syncing
+// after a new command lands gives that command (and only that command) a
+// fresher snapshot ts.
+
+const path = require("node:path");
+
+const {
+  ENTITY_TYPES,
+  EVENT_SUBTYPES,
+  ITEM_SUBTYPES,
+  CAPTURED_BY,
+} = require("../../constants");
+
+const {
+  defaultVscodeRoot,
+  decodeFileUri,
+  readWorkspaces,
+  readTerminalHistory,
+} = require("./vscode-reader");
+
+const NAME = "vscode";
+const VERSION = "0.1.0";
+
+class VSCodeAdapter {
+  constructor(opts = {}) {
+    this.name = NAME;
+    this.version = VERSION;
+    this.capabilities = [
+      "sync:vscode-workspace-storage",
+      "sync:vscode-globalstorage-sqlite",
+    ];
+    this.extractMode = "file-import";
+    this.rateLimits = { perDay: 96 };
+    this.dataDisclosure = {
+      fields: [
+        "workspaces:hash,folderUri,folderPath,lastOpenedMs",
+        "terminal-commands:command,shellType,sourceIndex,snapshotTs",
+        "terminal-dirs:dir,shellType,sourceIndex,snapshotTs",
+      ],
+      sensitivity: "high",
+      legalGate: false,
+      defaultInclude: { workspaces: true, terminal: true },
+    };
+    this._deps = {
+      fs: require("node:fs"),
+      defaultRoot: defaultVscodeRoot,
+    };
+    this._rootOverride = typeof opts.vscodeRoot === "string" ? opts.vscodeRoot : null;
+  }
+
+  _resolveRoot(opts) {
+    if (typeof opts?.vscodeRoot === "string" && opts.vscodeRoot.length > 0) {
+      return opts.vscodeRoot;
+    }
+    if (this._rootOverride) return this._rootOverride;
+    return this._deps.defaultRoot();
+  }
+
+  async authenticate(ctx = {}) {
+    const root = this._resolveRoot(ctx);
+    if (!root) {
+      return {
+        ok: false,
+        reason: "VSCODE_ROOT_UNRESOLVED",
+        message: "no default VSCode root on this platform; pass opts.vscodeRoot",
+      };
+    }
+    const wsRoot = path.join(root, "User", "workspaceStorage");
+    const stateDb = path.join(root, "User", "globalStorage", "state.vscdb");
+    const wsExists = this._deps.fs.existsSync(wsRoot);
+    const stateExists = this._deps.fs.existsSync(stateDb);
+    if (!wsExists && !stateExists) {
+      return {
+        ok: false,
+        reason: "VSCODE_NOT_FOUND",
+        message: `no VSCode state at ${root} — install VS Code / open it at least once, or pass opts.vscodeRoot`,
+      };
+    }
+    return {
+      ok: true,
+      mode: "file-import",
+      vscodeRoot: root,
+      hasWorkspaces: wsExists,
+      hasTerminalHistory: stateExists,
+    };
+  }
+
+  async healthCheck() {
+    const root = this._resolveRoot({});
+    const ok =
+      !!root &&
+      (this._deps.fs.existsSync(path.join(root, "User", "workspaceStorage")) ||
+        this._deps.fs.existsSync(path.join(root, "User", "globalStorage", "state.vscdb")));
+    return { ok, lastChecked: Date.now() };
+  }
+
+  async *sync(opts = {}) {
+    const root = this._resolveRoot(opts);
+    if (!root) {
+      throw new Error("vscode.sync: no VSCode root resolved — pass opts.vscodeRoot");
+    }
+    const includeWorkspaces = opts.include?.workspaces !== false;
+    const includeTerminal = opts.include?.terminal !== false;
+    const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : Infinity;
+    const capturedAt = Date.now();
+    let emitted = 0;
+
+    if (includeWorkspaces) {
+      for (const w of readWorkspaces(root, { fs: this._deps.fs, since: opts.since })) {
+        if (emitted >= limit) return;
+        yield {
+          kind: "workspace",
+          originalId: `vscode-workspace:${w.hash}`,
+          capturedAt,
+          payload: w,
+        };
+        emitted += 1;
+      }
+    }
+
+    if (includeTerminal) {
+      const hist = readTerminalHistory(root, { fs: this._deps.fs });
+      const cmdTs = Number.isInteger(hist.commandsTimestampMs)
+        ? hist.commandsTimestampMs
+        : capturedAt;
+      const dirTs = Number.isInteger(hist.dirsTimestampMs)
+        ? hist.dirsTimestampMs
+        : capturedAt;
+      if (opts.include?.terminalCommands !== false) {
+        for (const c of hist.commands) {
+          if (emitted >= limit) return;
+          if (Number.isInteger(opts.since) && cmdTs < opts.since) break;
+          yield {
+            kind: "terminal-command",
+            // Index disambiguates entries that re-occur with identical command
+            // text — keeps registry.putRawEvent's UNIQUE(source.originalId) happy.
+            originalId: `vscode-terminal-cmd:${c.sourceIndex}:${hashCommand(c.value)}`,
+            capturedAt,
+            payload: { ...c, snapshotTs: cmdTs },
+          };
+          emitted += 1;
+        }
+      }
+      if (opts.include?.terminalDirs !== false) {
+        for (const d of hist.dirs) {
+          if (emitted >= limit) return;
+          if (Number.isInteger(opts.since) && dirTs < opts.since) break;
+          yield {
+            kind: "terminal-dir",
+            originalId: `vscode-terminal-dir:${d.sourceIndex}:${hashCommand(d.value)}`,
+            capturedAt,
+            payload: { ...d, snapshotTs: dirTs },
+          };
+          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 === "workspace") {
+      const p = raw.payload || {};
+      const uri = p.folderUri || p.workspaceUri || `vscode-hash:${p.hash}`;
+      const name =
+        (p.folderPath && p.folderPath.split(/[\\/]/).filter(Boolean).pop()) ||
+        decodeFileUri(uri) ||
+        uri;
+      const item = {
+        id: `item-vscode-workspace-${p.hash}`,
+        type: ENTITY_TYPES.ITEM,
+        subtype: ITEM_SUBTYPES.LINK,
+        name: name || "(无名工程)",
+        category: "code-project",
+        ingestedAt,
+        source: source(`vscode-workspace:${p.hash}`),
+        extra: {
+          folderUri: p.folderUri || null,
+          workspaceUri: p.workspaceUri || null,
+          folderPath: p.folderPath || null,
+          lastOpenedMs: Number.isInteger(p.lastOpenedMs) ? p.lastOpenedMs : null,
+          editor: "vscode",
+        },
+      };
+      return { events: [], persons: [], places: [], items: [item], topics: [] };
+    }
+
+    if (raw.kind === "terminal-command") {
+      const p = raw.payload || {};
+      const cmd = typeof p.value === "string" ? p.value : "";
+      const event = {
+        id: `event-vscode-terminal-cmd-${p.sourceIndex}-${shortHash(cmd)}`,
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.OTHER,
+        occurredAt: Number.isInteger(p.snapshotTs) ? p.snapshotTs : raw.capturedAt,
+        ingestedAt,
+        source: source(raw.originalId),
+        actor: "self",
+        content: {
+          title: cmd.length > 80 ? cmd.substring(0, 80) + "…" : cmd,
+          text: cmd,
+        },
+        extra: {
+          kind: "terminal-command",
+          shellType: p.shellType || null,
+          sourceIndex: p.sourceIndex,
+          editor: "vscode",
+        },
+      };
+      return { events: [event], persons: [], places: [], items: [], topics: [] };
+    }
+
+    if (raw.kind === "terminal-dir") {
+      const p = raw.payload || {};
+      const dir = typeof p.value === "string" ? p.value : "";
+      const event = {
+        id: `event-vscode-terminal-dir-${p.sourceIndex}-${shortHash(dir)}`,
+        type: ENTITY_TYPES.EVENT,
+        subtype: EVENT_SUBTYPES.OTHER,
+        occurredAt: Number.isInteger(p.snapshotTs) ? p.snapshotTs : raw.capturedAt,
+        ingestedAt,
+        source: source(raw.originalId),
+        actor: "self",
+        content: {
+          title: `cd ${dir.length > 76 ? dir.substring(0, 76) + "…" : dir}`,
+          text: dir,
+        },
+        extra: {
+          kind: "terminal-dir",
+          shellType: p.shellType || null,
+          sourceIndex: p.sourceIndex,
+          editor: "vscode",
+        },
+      };
+      return { events: [event], persons: [], places: [], items: [], topics: [] };
+    }
+
+    throw new Error(`vscode.normalize: unknown raw.kind=${raw.kind}`);
+  }
+}
+
+// Cheap non-crypto hash for de-duping originalId + event id collisions.
+// Don't need cryptographic strength here — the registry UNIQUE constraint
+// gives the real guarantee.
+function hashCommand(s) {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) {
+    h = ((h << 5) + h + s.charCodeAt(i)) >>> 0;
+  }
+  return h.toString(36);
+}
+
+function shortHash(s) {
+  return hashCommand(s).substring(0, 8);
+}
+
+module.exports = {
+  VSCodeAdapter,
+  VSCODE_NAME: NAME,
+  VSCODE_VERSION: VERSION,
+};

package/lib/adapters/vscode/index.js

@@ -0,0 +1,18 @@
+"use strict";
+
+const {
+  VSCodeAdapter,
+  VSCODE_NAME,
+  VSCODE_VERSION,
+} = require("./adapter");
+const reader = require("./vscode-reader");
+
+module.exports = {
+  VSCodeAdapter,
+  VSCODE_NAME,
+  VSCODE_VERSION,
+  defaultVscodeRoot: reader.defaultVscodeRoot,
+  decodeFileUri: reader.decodeFileUri,
+  readWorkspaces: reader.readWorkspaces,
+  readTerminalHistory: reader.readTerminalHistory,
+};

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