@geml/logseq-sync 2.0.0 → 2.0.3

package/core/src/discovery.mjs

@@ -0,0 +1,204 @@
+// Everything the watcher can work out for itself. Each function takes a
+// `probe` — { platform, env, home, exists, read, listDir } — so the logic is
+// testable on any OS without a Logseq installation, and so `doctor` can report
+// exactly what was found and where.
+import { join } from "node:path";
+import { SIGNAL_FILE } from "./bridge.mjs";
+
+export const PLUGIN_ID = "logseq-plugin-sync-vault-with-geml";
+
+// The app bundle path is stable across macOS installs, and the shim the app
+// writes to ~/.local/bin is a two-line wrapper around exactly this pair.
+const MAC_APP = "/Applications/Logseq.app/Contents/MacOS/Logseq";
+const MAC_APP_CLI_JS = "/Applications/Logseq.app/Contents/Resources/app.asar/js/logseq-cli.js";
+
+/** Config, plugins and plugin storage — NOT where graphs live. */
+export function logseqDotDir(probe) {
+  return probe.env.LOGSEQ_DOTDIR || join(probe.home, ".logseq");
+}
+
+/** Graph root: `<root>/graphs/<name>/db.sqlite`. The app CLI calls it --root-dir. */
+export function logseqRootDir(probe) {
+  return probe.env.LOGSEQ_ROOT_DIR || join(probe.home, "logseq");
+}
+
+/** The file the in-app plugin touches to say "the graph changed". */
+export function signalFilePath(probe) {
+  return join(logseqDotDir(probe), "storages", PLUGIN_ID, SIGNAL_FILE);
+}
+
+/**
+ * What the user set in the plugin's own settings panel. Absent or half-written
+ * settings are not an error — they just mean "nothing configured yet".
+ */
+export function pluginSettings(probe) {
+  const path = join(logseqDotDir(probe), "settings", `${PLUGIN_ID}.json`);
+  try {
+    const parsed = JSON.parse(probe.read(path));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The launcher the app writes to its CLI install directory is a two-line
+ * wrapper it generates itself, and it stamps "logseq-cli-managed" into the
+ * file. On Windows that launcher is a .cmd, which Node cannot exec without a
+ * shell — but the two paths it names can be exec'd directly, which is all the
+ * wrapper does anyway. So: read it, do not run it.
+ * @returns {{command: string, argsPrefix: string[], env: Record<string,string>, how: string}|null}
+ */
+export function parseManagedShim(probe, path) {
+  let text;
+  try {
+    text = probe.read(path);
+  } catch {
+    return null;
+  }
+  if (!text.includes("logseq-cli-managed")) return null;
+  const quoted = [...text.matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+  const exe = quoted[0];
+  const cliJs = quoted.find((q) => q.endsWith(".js"));
+  if (!exe || !cliJs) return null;
+  return {
+    command: exe,
+    argsPrefix: [cliJs],
+    env: { ELECTRON_RUN_AS_NODE: "1" },
+    how: `read from the launcher at ${path}`,
+  };
+}
+
+/**
+ * Every plausible way to reach the app's CLI, best first.
+ *
+ * The ranking matters more than the search: what the app itself installed is
+ * something it chose, on a platform we may never have run on. Anything we
+ * DEDUCE — a launcher we parse, a bundle path we hardcoded — ranks below it,
+ * because those are our assumptions rather than the app's own answer.
+ *
+ * @returns {{command: string, argsPrefix: string[], env: Record<string,string>, how: string}[]}
+ */
+export function appCliCandidates(probe) {
+  const win = probe.platform === "win32";
+  const out = [];
+  const seen = new Set();
+  const add = (c) => {
+    if (c && !seen.has(c.command)) { seen.add(c.command); out.push(c); }
+  };
+
+  // A launcher, wherever we find it: exec it directly when we can, and read
+  // the paths out of it when we cannot (Windows .cmd).
+  const launcher = (path, how) => {
+    if (!probe.exists(path)) return null;
+    if (/\.(cmd|bat)$/i.test(path)) {
+      const parsed = parseManagedShim(probe, path);
+      return parsed && { ...parsed, how: `${how}, read rather than run` };
+    }
+    return { command: path, argsPrefix: [], env: {}, how };
+  };
+
+  // 1. On PATH — the app put it there for exactly this.
+  const sep = win ? ";" : ":";
+  for (const dir of (probe.env.PATH || "").split(sep).filter(Boolean)) {
+    for (const name of win ? ["logseq.exe", "logseq.cmd"] : ["logseq"]) {
+      add(launcher(join(dir, name), "found on PATH"));
+    }
+  }
+
+  // 2. The app's default CLI install directory, even when it is not on PATH.
+  for (const name of win ? ["logseq.exe", "logseq.cmd"] : ["logseq"]) {
+    add(launcher(join(probe.home, ".local", "bin", name), "the launcher the app installs"));
+  }
+
+  // 3. Last: a path we hardcoded. Verified before use, never assumed.
+  if (probe.platform === "darwin" && probe.exists(MAC_APP)) {
+    add({
+      command: MAC_APP,
+      argsPrefix: [MAC_APP_CLI_JS],
+      env: { ELECTRON_RUN_AS_NODE: "1" },
+      how: "the Logseq.app bundle",
+    });
+  }
+
+  return out;
+}
+
+/**
+ * The CLI to use. Pass `verify` — a function that actually tries a candidate —
+ * and the first one that works is returned, which beats any amount of guessing
+ * about where things live on an OS or version we have not run on.
+ * @param {(candidate: object) => boolean} [verify]
+ */
+export function findAppCli(probe, verify) {
+  const candidates = appCliCandidates(probe);
+  if (!verify) return candidates[0] ?? null;
+  for (const c of candidates) {
+    if (verify(c)) return c;
+  }
+  return null;
+}
+
+/**
+ * Which graph to sync.
+ * @returns {{name: string, how: string}|{candidates: string[]}|null}
+ *   a name when it is unambiguous, a candidate list when the user must choose,
+ *   null when there are no graphs at all.
+ */
+export function detectGraph(probe) {
+  const graphsDir = join(logseqRootDir(probe), "graphs");
+  const all = probe.listDir(graphsDir).filter((n) => !n.startsWith("."));
+  if (all.length === 0) return null;
+
+  // A db-worker lock says a worker exists, not that the app has the graph open:
+  // every `logseq graph export` starts one of its own and leaves the file
+  // behind. Only the desktop app stamps owner-source "electron", and that is
+  // the graph whose sqlite the direct exporter cannot read.
+  const open = all.filter((name) => {
+    try {
+      return JSON.parse(probe.read(join(graphsDir, name, "db-worker.lock")))["owner-source"] === "electron";
+    } catch {
+      return false;
+    }
+  });
+  if (open.length === 1) return { name: open[0], how: "open in the app", graphs: all };
+  if (all.length === 1) return { name: all[0], how: "the only graph", graphs: all };
+
+  return { candidates: all, graphs: all };
+}
+
+/**
+ * The same question as detectGraph, asked of the CLI instead of the filesystem.
+ * `graph list` and `server list` are the app's own answers, so this holds on
+ * any OS and for a graph root nobody left in the default place — and
+ * owner-source comes from the app rather than from reading its lock files.
+ *
+ * @param {(args: string[]) => string} runCli returns stdout, or throws
+ * @returns {{name: string, how: string, graphs: string[], rootDir: string|null}
+ *          |{candidates: string[], graphs: string[], rootDir: string|null}
+ *          |null} null means "could not ask" — the caller should fall back.
+ */
+export function detectGraphViaCli(runCli) {
+  let graphs;
+  try {
+    graphs = JSON.parse(runCli(["graph", "list", "-o", "json"]))?.data?.graphs;
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(graphs) || graphs.length === 0) return null;
+
+  // Servers are a bonus, not a requirement: with none running we still know
+  // the graphs, we just cannot tell which one the app has open.
+  let open = null;
+  let rootDir = null;
+  try {
+    const servers = JSON.parse(runCli(["server", "list", "-o", "json"]))?.data?.servers ?? [];
+    rootDir = servers[0]?.["root-dir"] ?? null;
+    const appOwned = servers.filter((s) => s?.["owner-source"] === "electron");
+    if (appOwned.length === 1) open = appOwned[0].graph;
+  } catch {}
+
+  if (open && graphs.includes(open)) return { name: open, how: "open in the app", graphs, rootDir };
+  if (graphs.length === 1) return { name: graphs[0], how: "the only graph", graphs, rootDir };
+  return { candidates: graphs, graphs, rootDir };
+}

package/core/src/sync-engine.mjs

@@ -12,7 +12,7 @@ import {
   renameSync,
   existsSync,
 } from "node:fs";
-import { join, dirname, relative, resolve, sep } from "node:path";
+import { join, dirname, relative, resolve, sep, isAbsolute } from "node:path";
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { ednToGemlFiles, gemlFilesToEdn } from "./mapping.mjs";
@@ -297,8 +297,38 @@ export async function syncEdnToDisk(ednText, targetDir, opts = {}) {
 
   const diffResult = writeGemlFilesToDisk(gemlFiles, targetDir, opts);
 
+  // A parallel Markdown tree, for people and tools that read Markdown and
+  // nothing else. Deliberately lossy and deliberately separate: the GEML tree
+  // stays the one that round-trips. The converter is injected, so this module
+  // keeps its single dependency.
+  const markdownWritten = [];
+  if (opts.markdownDir && typeof opts.gemlToMd === "function") {
+    for (const [rel, content] of gemlFiles) {
+      const mdRel = rel.replace(/\.geml$/, ".md");
+      const full = join(opts.markdownDir, mdRel);
+      let md;
+      try {
+        md = normalizeEol(opts.gemlToMd(content));
+      } catch {
+        continue; // one unconvertible document must not fail the sync
+      }
+      mkdirSync(dirname(full), { recursive: true });
+      if (!existsSync(full) || readFileSync(full, "utf8") !== md) {
+        atomicWriteFileSync(full, md);
+        markdownWritten.push(mdRel);
+      }
+    }
+  }
+
   let gitResult = null;
   const pathsModified = [...diffResult.written, ...diffResult.deleted];
+  for (const rel of markdownWritten) {
+    const abs = join(opts.markdownDir, rel);
+    const insideVault = relative(targetDir, abs);
+    if (insideVault && !insideVault.startsWith("..") && !isAbsolute(insideVault)) {
+      pathsModified.push(insideVault);
+    }
+  }
 
   if (opts.autoCommit && pathsModified.length > 0) {
     const msg = opts.commitMessage || `logseq-geml: synced ${diffResult.written.length} modified, ${diffResult.deleted.length} deleted`;
@@ -307,6 +337,7 @@ export async function syncEdnToDisk(ednText, targetDir, opts = {}) {
 
   return {
     ...diffResult,
+    markdownWritten,
     gitResult,
   };
 }

package/docs/how-it-works.svg

@@ -25,7 +25,7 @@
 
   <!-- watcher box -->
   <rect x="488" y="36" width="248" height="130" rx="10" fill="#ffffff" stroke="#2da44e" stroke-width="1.5"/>
-  <text x="612" y="62" text-anchor="middle" font-size="15" font-weight="700" fill="#57606a">geml-sync watcher (CLI)</text>
+  <text x="612" y="62" text-anchor="middle" font-size="15" font-weight="700" fill="#57606a">logseq-sync watcher (CLI)</text>
   <text x="612" y="86" text-anchor="middle" font-size="11.5" fill="#57606a">export via official @logseq/cli</text>
   <text x="612" y="103" text-anchor="middle" font-size="11.5" fill="#57606a">writes only files that changed</text>
   <text x="612" y="120" text-anchor="middle" font-size="11.5" fill="#57606a">git commit scoped to the vault</text>

package/package.json

@@ -1,53 +1,54 @@
-{
-  "name": "@geml/logseq-sync",
-  "version": "2.0.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "description": "Continuously sync a Logseq DB graph to a Git-friendly folder of readable plain-text GEML files — the watcher half of the Sync Vault with GEML plugin. Built on the official @logseq/cli export; writes only files that changed, commits scoped strictly to the vault.",
-  "type": "module",
-  "bin": {
-    "geml-sync": "watcher/bin/geml-sync.mjs"
-  },
-  "files": [
-    "core/src",
-    "watcher/bin",
-    "docs",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "keywords": [
-    "logseq",
-    "logseq-plugin",
-    "sync",
-    "git",
-    "plain-text",
-    "geml",
-    "vault",
-    "backup"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/geml-spec/geml.git",
-    "directory": "integrations/logseq"
-  },
-  "homepage": "https://github.com/geml-spec/logseq-plugin-sync-vault-with-geml#readme",
-  "bugs": {
-    "url": "https://github.com/geml-spec/logseq-plugin-sync-vault-with-geml/issues"
-  },
-  "license": "MIT",
-  "workspaces": [
-    "plugin"
-  ],
-  "scripts": {
-    "test": "node core/test/roundtrip.test.mjs && node core/test/sync.test.mjs && node watcher/test/cli-sync.test.mjs && node watcher/test/signal-sync.test.mjs && node plugin/test/core.test.mjs",
-    "sync": "node watcher/bin/geml-sync.mjs",
-    "build:plugin": "node plugin/build.mjs"
-  },
-  "dependencies": {
-    "edn-data": "^1.2.2"
-  }
-}
+{
+  "name": "@geml/logseq-sync",
+  "version": "2.0.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Continuously sync a Logseq DB graph to a Git-friendly folder of readable plain-text GEML files — the watcher half of the Sync Vault with GEML plugin. Built on the official @logseq/cli export; writes only files that changed, commits scoped strictly to the vault.",
+  "type": "module",
+  "bin": {
+    "logseq-sync": "watcher/bin/logseq-sync.mjs"
+  },
+  "files": [
+    "core/src",
+    "watcher/bin",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "logseq",
+    "logseq-plugin",
+    "sync",
+    "git",
+    "plain-text",
+    "geml",
+    "vault",
+    "backup"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geml-spec/geml.git",
+    "directory": "integrations/logseq"
+  },
+  "homepage": "https://github.com/geml-spec/logseq-plugin-sync-vault-with-geml#readme",
+  "bugs": {
+    "url": "https://github.com/geml-spec/logseq-plugin-sync-vault-with-geml/issues"
+  },
+  "license": "MIT",
+  "workspaces": [
+    "plugin"
+  ],
+  "scripts": {
+    "test": "node core/test/roundtrip.test.mjs && node core/test/sync.test.mjs && node core/test/discovery.test.mjs && node watcher/test/cli-sync.test.mjs && node watcher/test/signal-sync.test.mjs && node watcher/test/zero-config.test.mjs && node plugin/test/core.test.mjs",
+    "sync": "node watcher/bin/logseq-sync.mjs",
+    "build:plugin": "node plugin/build.mjs"
+  },
+  "dependencies": {
+    "@geml/geml": "^1.8.6",
+    "edn-data": "^1.2.2"
+  }
+}