@geml/logseq-sync 2.0.8 → 2.0.9

package/core/src/sync-engine.mjs

@@ -19,6 +19,11 @@ import { ednToGemlFiles, gemlFilesToEdn } from "./mapping.mjs";
 import { gemlToOgMarkdown } from "./og-markdown.mjs";
 
 const MANIFEST_FILE = ".geml-manifest.json";
+// The Markdown tree needs a ledger of its own: `--markdown` takes ANY
+// directory, so it is the tree most likely to be pointed at a graph someone
+// already has, and it must know which .md files are its own writes before it
+// overwrites one. A separate file because markdownDir may BE targetDir.
+const MD_MANIFEST_FILE = ".geml-md-manifest.json";
 
 const sha256 = (s) => createHash("sha256").update(s).digest("hex");
 
@@ -31,8 +36,8 @@ const sha256 = (s) => createHash("sha256").update(s).digest("hex");
  * watcher's own last write, not something a person or agent changed.
  * @returns {{ known: boolean, hashed: boolean, files: Map<string, string|null> }}
  */
-function readManifest(targetDir) {
-  const manifestPath = join(targetDir, MANIFEST_FILE);
+function readManifest(targetDir, manifestFile = MANIFEST_FILE) {
+  const manifestPath = join(targetDir, manifestFile);
   if (!existsSync(manifestPath)) return { known: false, hashed: false, files: new Map() };
   try {
     const parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
@@ -159,6 +164,38 @@ export function readGemlFilesFromDisk(dir, baseDir = dir) {
   return files;
 }
 
+/**
+ * Count the Markdown pages of an OG graph laid out under dir.
+ * readGemlFilesFromDisk answers "what of ours is here"; this answers "is this
+ * already somebody's graph", which is a different question and the one the
+ * empty-export guard actually asks.
+ */
+function countMarkdownPages(dir) {
+  let count = 0;
+  for (const sub of ["pages", "journals"]) {
+    const root = join(dir, sub);
+    if (!existsSync(root)) continue;
+    const stack = [root];
+    while (stack.length > 0) {
+      const current = stack.pop();
+      let entries;
+      try {
+        entries = readdirSync(current, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          if (!entry.name.startsWith(".") && entry.name !== "node_modules") stack.push(join(current, entry.name));
+        } else if (entry.isFile() && entry.name.endsWith(".md")) {
+          count += 1;
+        }
+      }
+    }
+  }
+  return count;
+}
+
 /**
  * Incrementally sync a Map of GEML files to disk.
  * Only writes files whose content has changed or do not yet exist.
@@ -176,16 +213,22 @@ export function readGemlFilesFromDisk(dir, baseDir = dir) {
  * @param {string[]} [opts.preserve] Files NOT to overwrite even when the graph
  *   differs — the conflicted files of a two-way cycle. Their manifest entry
  *   keeps its previous hash, so they stay flagged until a person resolves them.
- * @returns {{ written: string[], orphaned: string[], unchanged: string[], deleted: string[], preserved: string[] }}
+ * @param {boolean} [opts.overwriteUnmanaged=false] Overwrite files that exist
+ *   on disk but that no manifest ever claimed. Off by default: a vault IS a
+ *   graph, so people point this at one they already have, and a file we never
+ *   wrote is theirs, not our own echo.
+ * @returns {{ written: string[], orphaned: string[], unchanged: string[], deleted: string[], preserved: string[], unmanaged: string[] }}
  */
 export function writeGemlFilesToDisk(gemlFiles, targetDir, opts = {}) {
   const deleteOrphans = opts.deleteOrphans ?? false;
+  const overwriteUnmanaged = opts.overwriteUnmanaged ?? false;
   const preserve = new Set(opts.preserve ?? []);
   const written = [];
   const unchanged = [];
   const orphaned = [];
   const deleted = [];
   const preserved = [];
+  const unmanaged = [];
 
   mkdirSync(targetDir, { recursive: true });
   const existingFiles = readGemlFilesFromDisk(targetDir);
@@ -204,6 +247,17 @@ export function writeGemlFilesToDisk(gemlFiles, targetDir, opts = {}) {
     if (preserve.has(rel)) {
       if (existingContent !== normNew) preserved.push(rel);
       else unchanged.push(rel);
+    } else if (
+      existingContent !== undefined &&
+      existingContent !== normNew &&
+      !lastManifest.has(rel) &&
+      !overwriteUnmanaged
+    ) {
+      // On disk, different from the graph, and no manifest ever claimed it:
+      // someone else's file, not our own echo. A file that already MATCHES
+      // what we would write falls through and is adopted — identical bytes
+      // mean there is nothing of theirs to lose.
+      unmanaged.push(rel);
     } else if (existingContent === undefined || existingContent !== normNew) {
       atomicWriteFileSync(fullPath, normNew);
       written.push(rel);
@@ -235,6 +289,9 @@ export function writeGemlFilesToDisk(gemlFiles, targetDir, opts = {}) {
   // detectExternalEdits() compares against, so the watcher's own writes never
   // read as someone else's edits.
   const currentManifest = new Set(gemlFiles.keys());
+  // A held file stays unowned: recording a hash for it would make the next run
+  // read the person's content as the sync's own last write and clobber it.
+  for (const rel of unmanaged) currentManifest.delete(rel);
   for (const rel of lastManifest) {
     if (existingFiles.has(rel) && !deleted.includes(rel)) {
       currentManifest.add(rel);
@@ -254,7 +311,7 @@ export function writeGemlFilesToDisk(gemlFiles, targetDir, opts = {}) {
   }
   atomicWriteFileSync(manifestPath, JSON.stringify({ version: 2, files: manifestFiles }, null, 1) + "\n");
 
-  return { written, orphaned, unchanged, deleted, preserved };
+  return { written, orphaned, unchanged, deleted, preserved, unmanaged };
 }
 
 /**
@@ -364,10 +421,14 @@ export async function gitAutoCommit(targetDir, commitMessage = "logseq-geml sync
  * @param {boolean} [opts.autoCommit=false]
  * @param {string} [opts.commitMessage]
  * @param {boolean} [opts.allowEmptyGraph=false] Refuse 0-page export over non-empty targetDir unless true.
+ * @param {boolean} [opts.overwriteUnmanaged=false] Overwrite files no manifest
+ *   ever claimed, in BOTH trees. Off by default — see writeGemlFilesToDisk.
  * @param {function} [opts.gitRunner]
- * @returns {Promise<{ written: string[], deleted: string[], orphaned: string[], unchanged: string[], gitResult?: any }>}
+ * @returns {Promise<{ written: string[], deleted: string[], orphaned: string[], unchanged: string[], unmanaged: string[], markdownWritten: string[], markdownUnmanaged: string[], gitResult?: any }>}
  */
 export async function syncEdnToDisk(ednText, targetDir, opts = {}) {
+  const overwriteUnmanaged = opts.overwriteUnmanaged ?? false;
+
   // Guard 1: Refuse empty or truncated EDN input
   if (!ednText || typeof ednText !== "string" || ednText.trim().length === 0) {
     throw new Error("EDN input is empty or truncated; refusing to sync to prevent data loss.");
@@ -378,7 +439,14 @@ export async function syncEdnToDisk(ednText, targetDir, opts = {}) {
   // Guard 2: Refuse 0-page export if targetDir already has existing pages
   const pageCount = [...gemlFiles.keys()].filter((k) => k.startsWith("pages/") || k.startsWith("journals/")).length;
   const existingFiles = readGemlFilesFromDisk(targetDir);
-  const existingPageCount = [...existingFiles.keys()].filter((k) => k.startsWith("pages/") || k.startsWith("journals/")).length;
+  // Counting only .geml left this guard blind to exactly what it guards
+  // against: a directory that is ALREADY an OG graph holds its pages as
+  // Markdown, and readGemlFilesFromDisk does not see one of them.
+  const markdownDir = opts.markdownDir ?? null;
+  const existingPageCount =
+    [...existingFiles.keys()].filter((k) => k.startsWith("pages/") || k.startsWith("journals/")).length +
+    countMarkdownPages(targetDir) +
+    (markdownDir && resolve(markdownDir) !== resolve(targetDir) ? countMarkdownPages(markdownDir) : 0);
 
   if (pageCount === 0 && existingPageCount > 0 && !opts.allowEmptyGraph) {
     throw new Error(
@@ -399,13 +467,16 @@ export async function syncEdnToDisk(ednText, targetDir, opts = {}) {
   // round-trips, and `restore` never reads this. The parser library is
   // injected, so core keeps its single dependency.
   const markdownWritten = [];
-  if (opts.markdownDir && opts.lib) {
+  const markdownUnmanaged = [];
+  if (markdownDir && opts.lib) {
+    const mdPrevious = readManifest(markdownDir, MD_MANIFEST_FILE);
+    const mdManifest = {};
     for (const [rel, content] of gemlFiles) {
       // Only pages and journals are a graph; the index and the ontology carry
       // machine bookkeeping OG has no page for.
       if (!rel.startsWith("pages/") && !rel.startsWith("journals/")) continue;
       const mdRel = rel.replace(/\.geml$/, ".md");
-      const full = join(opts.markdownDir, mdRel);
+      const full = join(markdownDir, mdRel);
       let md;
       try {
         md = normalizeEol(gemlToOgMarkdown(content, opts.lib));
@@ -413,18 +484,46 @@ export async function syncEdnToDisk(ednText, targetDir, opts = {}) {
         continue; // one unconvertible document must not fail the sync
       }
       if (md === "") continue; // nothing OG can hold — write no file
-      mkdirSync(dirname(full), { recursive: true });
-      if (!existsSync(full) || readFileSync(full, "utf8") !== md) {
+      const onDisk = existsSync(full) ? normalizeEol(readFileSync(full, "utf8")) : null;
+      if (onDisk !== null && onDisk !== md && !mdPrevious.files.has(mdRel) && !overwriteUnmanaged) {
+        // The GEML tree's rule, and this tree needs it more: `--markdown` takes
+        // any directory, so somebody's own pages/*.md is precisely what it
+        // lands on. Held, named, and left exactly as they wrote it.
+        markdownUnmanaged.push(mdRel);
+        continue;
+      }
+      if (onDisk !== md) {
+        mkdirSync(dirname(full), { recursive: true });
         atomicWriteFileSync(full, md);
         markdownWritten.push(mdRel);
       }
+      mdManifest[mdRel] = sha256(md);
+    }
+    // A page the graph stopped exporting keeps its entry while the file is
+    // still there: dropping it would make our own past write read as a
+    // stranger's on the next run, and the sync would refuse to touch it.
+    for (const [mdRel, hash] of mdPrevious.files) {
+      if (!(mdRel in mdManifest) && existsSync(join(markdownDir, mdRel))) mdManifest[mdRel] = hash;
+    }
+    const mdManifestPath = join(markdownDir, MD_MANIFEST_FILE);
+    const mdManifestFiles = {};
+    for (const mdRel of Object.keys(mdManifest).sort()) mdManifestFiles[mdRel] = mdManifest[mdRel];
+    const mdManifestText = JSON.stringify({ version: 2, files: mdManifestFiles }, null, 1) + "\n";
+    const mdManifestExists = existsSync(mdManifestPath);
+    // Only when it actually changed: this file lives inside someone's OG graph,
+    // and rewriting it every poll would have Logseq re-reading it forever.
+    if (
+      (Object.keys(mdManifestFiles).length > 0 || mdManifestExists) &&
+      (!mdManifestExists || readFileSync(mdManifestPath, "utf8") !== mdManifestText)
+    ) {
+      atomicWriteFileSync(mdManifestPath, mdManifestText);
     }
   }
 
   let gitResult = null;
   const pathsModified = [...diffResult.written, ...diffResult.deleted];
   for (const rel of markdownWritten) {
-    const abs = join(opts.markdownDir, rel);
+    const abs = join(markdownDir, rel);
     const insideVault = relative(targetDir, abs);
     if (insideVault && !insideVault.startsWith("..") && !isAbsolute(insideVault)) {
       pathsModified.push(insideVault);
@@ -439,6 +538,7 @@ export async function syncEdnToDisk(ednText, targetDir, opts = {}) {
   return {
     ...diffResult,
     markdownWritten,
+    markdownUnmanaged,
     gitResult,
   };
 }

package/docs/how-it-works.svg

@@ -1,42 +1,42 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 250" font-family="ui-sans-serif,system-ui,Segoe UI,Helvetica,Arial,sans-serif">
-  <defs>
-    <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
-      <path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/>
-    </marker>
-  </defs>
-  <rect x="0" y="0" width="760" height="250" rx="12" fill="#f6f8fa" stroke="#d0d7de"/>
-
-  <!-- Logseq app box -->
-  <rect x="24" y="36" width="220" height="130" rx="10" fill="#ffffff" stroke="#a475f9" stroke-width="1.5"/>
-  <text x="134" y="62" text-anchor="middle" font-size="15" font-weight="700" fill="#57606a">Logseq 2.0 (DB graph)</text>
-  <rect x="44" y="80" width="180" height="66" rx="8" fill="#f3ecff" stroke="#a475f9"/>
-  <text x="134" y="104" text-anchor="middle" font-size="13" font-weight="600" fill="#3b2a63">Sync Vault with GEML plugin</text>
-  <text x="134" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">DB.onChanged → debounce</text>
-  <text x="134" y="139" text-anchor="middle" font-size="11.5" fill="#57606a">status in toolbar ⇄</text>
-
-  <!-- signal file -->
-  <rect x="286" y="70" width="160" height="42" rx="8" fill="#fff8c5" stroke="#d4a72c"/>
-  <text x="366" y="88" text-anchor="middle" font-size="12" font-weight="600" fill="#57606a">dirty-marker file</text>
-  <text x="366" y="103" text-anchor="middle" font-size="10.5" fill="#7d8590">…/storages/logseq-plugin-sync-vault-with-geml/</text>
-
-  <!-- status file -->
-  <rect x="286" y="128" width="160" height="34" rx="8" fill="#ddf4ff" stroke="#54aeff"/>
-  <text x="366" y="149" text-anchor="middle" font-size="12" font-weight="600" fill="#57606a">geml-sync-status.json</text>
-
-  <!-- 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">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>
-  <text x="612" y="145" text-anchor="middle" font-size="11.5" font-weight="600" fill="#2da44e">your-vault/pages/*.geml · git</text>
-
-  <!-- arrows -->
-  <line x1="244" y1="91" x2="284" y2="91" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
-  <line x1="446" y1="91" x2="486" y2="91" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
-  <line x1="486" y1="145" x2="446" y2="145" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
-  <line x1="286" y1="145" x2="246" y2="145" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
-
-  <text x="380" y="196" text-anchor="middle" font-size="12.5" fill="#57606a">The plugin is a doorbell, not the mover: the sandbox has no filesystem and no git,</text>
-  <text x="380" y="214" text-anchor="middle" font-size="12.5" fill="#57606a">so everything with side effects lives in the watcher — auditable, scoped, outside the app.</text>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 250" font-family="ui-sans-serif,system-ui,Segoe UI,Helvetica,Arial,sans-serif">
+  <defs>
+    <marker id="arr" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0 L10,5 L0,10 z" fill="#8b949e"/>
+    </marker>
+  </defs>
+  <rect x="0" y="0" width="760" height="250" rx="12" fill="#f6f8fa" stroke="#d0d7de"/>
+
+  <!-- Logseq app box -->
+  <rect x="24" y="36" width="220" height="130" rx="10" fill="#ffffff" stroke="#a475f9" stroke-width="1.5"/>
+  <text x="134" y="62" text-anchor="middle" font-size="15" font-weight="700" fill="#57606a">Logseq 2.0 (DB graph)</text>
+  <rect x="44" y="80" width="180" height="66" rx="8" fill="#f3ecff" stroke="#a475f9"/>
+  <text x="134" y="104" text-anchor="middle" font-size="13" font-weight="600" fill="#3b2a63">Sync Vault with GEML plugin</text>
+  <text x="134" y="124" text-anchor="middle" font-size="11.5" fill="#57606a">DB.onChanged → debounce</text>
+  <text x="134" y="139" text-anchor="middle" font-size="11.5" fill="#57606a">status in toolbar ⇄</text>
+
+  <!-- signal file -->
+  <rect x="286" y="70" width="160" height="42" rx="8" fill="#fff8c5" stroke="#d4a72c"/>
+  <text x="366" y="88" text-anchor="middle" font-size="12" font-weight="600" fill="#57606a">dirty-marker file</text>
+  <text x="366" y="103" text-anchor="middle" font-size="10.5" fill="#7d8590">…/storages/logseq-plugin-sync-vault-with-geml/</text>
+
+  <!-- status file -->
+  <rect x="286" y="128" width="160" height="34" rx="8" fill="#ddf4ff" stroke="#54aeff"/>
+  <text x="366" y="149" text-anchor="middle" font-size="12" font-weight="600" fill="#57606a">geml-sync-status.json</text>
+
+  <!-- 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">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>
+  <text x="612" y="145" text-anchor="middle" font-size="11.5" font-weight="600" fill="#2da44e">your-vault/pages/*.geml · git</text>
+
+  <!-- arrows -->
+  <line x1="244" y1="91" x2="284" y2="91" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+  <line x1="446" y1="91" x2="486" y2="91" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+  <line x1="486" y1="145" x2="446" y2="145" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+  <line x1="286" y1="145" x2="246" y2="145" stroke="#8b949e" stroke-width="1.6" marker-end="url(#arr)"/>
+
+  <text x="380" y="196" text-anchor="middle" font-size="12.5" fill="#57606a">The plugin is a doorbell, not the mover: the sandbox has no filesystem and no git,</text>
+  <text x="380" y="214" text-anchor="middle" font-size="12.5" fill="#57606a">so everything with side effects lives in the watcher — auditable, scoped, outside the app.</text>
+</svg>

package/package.json

@@ -1,54 +1,58 @@
-{
-  "name": "@geml/logseq-sync",
-  "version": "2.0.8",
-  "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.8",
-    "edn-data": "^1.2.2"
-  }
-}
+{
+  "name": "@geml/logseq-sync",
+  "version": "2.0.9",
+  "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.8",
+    "edn-data": "^1.2.2"
+  },
+  "overrides": {
+    "dompurify": "^3.4.14",
+    "lodash-es": "^4.18.1"
+  }
+}

package/watcher/bin/create-graph.mjs

@@ -1,51 +1,51 @@
-// Create an empty Logseq DB graph WITHOUT the desktop app.
-//
-//   LOGSEQ_CLI_DIR=<dir whose node_modules holds @logseq/cli>  \
-//   node bin/create-graph.mjs <graph-name>   (name travels via GEML_GRAPH_NAME —
-//   nbb loadFile does not surface *command-line-args*)
-//
-// Why this exists: `@logseq/cli` (0.4.3) can export, import and validate a DB
-// graph, but cannot create one — creation lives in the desktop app, and on a
-// machine where the app cannot run (permissions, CI) that is a dead end. The
-// CLI package VENDORS the whole logseq.db stack though, and its `open-db!`
-// creates the sqlite tables on open; the only other thing the app does at
-// create time is transact `build-db-initial-data`. So this does exactly those
-// two steps, through the CLI's own vendored code — the resulting graph is one
-// `logseq list/show/validate` accepts as its own (verified: schema 65.22,
-// "Valid!").
-import { fileURLToPath, pathToFileURL } from "url";
-import { dirname, resolve } from "path";
-import { existsSync, readFileSync, copyFileSync, rmSync } from "fs";
-
-const here = fileURLToPath(dirname(import.meta.url));
-const cliDir = process.env.LOGSEQ_CLI_DIR ?? resolve(here, "..");
-const CLI = resolve(cliDir, "node_modules", "@logseq", "cli");
-if (!existsSync(CLI)) {
-  console.error(`@logseq/cli not found under ${cliDir}/node_modules — set LOGSEQ_CLI_DIR to a directory where it is installed.`);
-  console.error("Note: on Node 24 its better-sqlite3 needs an override to >=12.11.1 for a prebuilt binding.");
-  process.exit(2);
-}
-
-// nbb-logseq is resolved from the CLI's install, not from this package: ESM
-// import specifiers resolve relative to THIS file, which would demand a local
-// install of a runtime the CLI already carries.
-const nbbDir = resolve(cliDir, "node_modules", "@logseq", "nbb-logseq");
-const nbbPkg = JSON.parse(readFileSync(resolve(nbbDir, "package.json"), "utf8"));
-const entry = typeof nbbPkg.exports === "object"
-  ? (nbbPkg.exports["."]?.import ?? nbbPkg.exports["."]) : (nbbPkg.main ?? "index.mjs");
-const { loadFile, addClassPath } = await import(pathToFileURL(resolve(nbbDir, entry)).href);
-
-global.__dirname = here;
-addClassPath(resolve(CLI, "src"));
-addClassPath(resolve(CLI, "vendor/src"));
-// nbb resolves the stack's node `require`s (better-sqlite3) relative to the
-// LOADED FILE's directory, so the .cljs must sit beside a node_modules that
-// has them — copy it into the CLI dir for the duration of the run.
-process.env.GEML_GRAPH_NAME = process.argv[2] ?? "geml-spike";
-const staged = resolve(cliDir, ".geml-create-graph.cljs");
-copyFileSync(resolve(here, "create_graph_headless.cljs"), staged);
-try {
-  await loadFile(staged);
-} finally {
-  rmSync(staged, { force: true });
-}
+// Create an empty Logseq DB graph WITHOUT the desktop app.
+//
+//   LOGSEQ_CLI_DIR=<dir whose node_modules holds @logseq/cli>  \
+//   node bin/create-graph.mjs <graph-name>   (name travels via GEML_GRAPH_NAME —
+//   nbb loadFile does not surface *command-line-args*)
+//
+// Why this exists: `@logseq/cli` (0.4.3) can export, import and validate a DB
+// graph, but cannot create one — creation lives in the desktop app, and on a
+// machine where the app cannot run (permissions, CI) that is a dead end. The
+// CLI package VENDORS the whole logseq.db stack though, and its `open-db!`
+// creates the sqlite tables on open; the only other thing the app does at
+// create time is transact `build-db-initial-data`. So this does exactly those
+// two steps, through the CLI's own vendored code — the resulting graph is one
+// `logseq list/show/validate` accepts as its own (verified: schema 65.22,
+// "Valid!").
+import { fileURLToPath, pathToFileURL } from "url";
+import { dirname, resolve } from "path";
+import { existsSync, readFileSync, copyFileSync, rmSync } from "fs";
+
+const here = fileURLToPath(dirname(import.meta.url));
+const cliDir = process.env.LOGSEQ_CLI_DIR ?? resolve(here, "..");
+const CLI = resolve(cliDir, "node_modules", "@logseq", "cli");
+if (!existsSync(CLI)) {
+  console.error(`@logseq/cli not found under ${cliDir}/node_modules — set LOGSEQ_CLI_DIR to a directory where it is installed.`);
+  console.error("Note: on Node 24 its better-sqlite3 needs an override to >=12.11.1 for a prebuilt binding.");
+  process.exit(2);
+}
+
+// nbb-logseq is resolved from the CLI's install, not from this package: ESM
+// import specifiers resolve relative to THIS file, which would demand a local
+// install of a runtime the CLI already carries.
+const nbbDir = resolve(cliDir, "node_modules", "@logseq", "nbb-logseq");
+const nbbPkg = JSON.parse(readFileSync(resolve(nbbDir, "package.json"), "utf8"));
+const entry = typeof nbbPkg.exports === "object"
+  ? (nbbPkg.exports["."]?.import ?? nbbPkg.exports["."]) : (nbbPkg.main ?? "index.mjs");
+const { loadFile, addClassPath } = await import(pathToFileURL(resolve(nbbDir, entry)).href);
+
+global.__dirname = here;
+addClassPath(resolve(CLI, "src"));
+addClassPath(resolve(CLI, "vendor/src"));
+// nbb resolves the stack's node `require`s (better-sqlite3) relative to the
+// LOADED FILE's directory, so the .cljs must sit beside a node_modules that
+// has them — copy it into the CLI dir for the duration of the run.
+process.env.GEML_GRAPH_NAME = process.argv[2] ?? "geml-spike";
+const staged = resolve(cliDir, ".geml-create-graph.cljs");
+copyFileSync(resolve(here, "create_graph_headless.cljs"), staged);
+try {
+  await loadFile(staged);
+} finally {
+  rmSync(staged, { force: true });
+}

package/watcher/bin/create_graph_headless.cljs

@@ -1,22 +1,22 @@
-(ns create-graph-headless
-  "Create an empty Logseq DB graph without the desktop app: the CLI package
-   vendors the whole logseq.db stack, and open-db! creates tables on open.
-   This does exactly what the app's create-graph does at the db level:
-   mkdir + open + transact build-db-initial-data.
-
-   open-db! creates the DATABASE but refuses a missing DIRECTORY (its error
-   says only 'Cannot open database because the directory does not exist'),
-   so the mkdir here is load-bearing."
-  (:require [logseq.db.common.sqlite-cli :as sqlite-cli]
-            [logseq.db.sqlite.create-graph :as sqlite-create-graph]
-            [datascript.core :as d]
-            ["fs" :as fs]
-            ["os" :as os]
-            ["path" :as node-path]))
-
-(def graph-name (or (aget (.-env js/process) "GEML_GRAPH_NAME") "geml-spike"))
-(def graphs-dir (node-path/join (os/homedir) "logseq" "graphs"))
-(fs/mkdirSync (node-path/join graphs-dir graph-name) #js {:recursive true})
-(def conn (sqlite-cli/open-db! graphs-dir graph-name))
-(d/transact! conn (sqlite-create-graph/build-db-initial-data "{}"))
-(println "created" (node-path/join graphs-dir graph-name))
+(ns create-graph-headless
+  "Create an empty Logseq DB graph without the desktop app: the CLI package
+   vendors the whole logseq.db stack, and open-db! creates tables on open.
+   This does exactly what the app's create-graph does at the db level:
+   mkdir + open + transact build-db-initial-data.
+
+   open-db! creates the DATABASE but refuses a missing DIRECTORY (its error
+   says only 'Cannot open database because the directory does not exist'),
+   so the mkdir here is load-bearing."
+  (:require [logseq.db.common.sqlite-cli :as sqlite-cli]
+            [logseq.db.sqlite.create-graph :as sqlite-create-graph]
+            [datascript.core :as d]
+            ["fs" :as fs]
+            ["os" :as os]
+            ["path" :as node-path]))
+
+(def graph-name (or (aget (.-env js/process) "GEML_GRAPH_NAME") "geml-spike"))
+(def graphs-dir (node-path/join (os/homedir) "logseq" "graphs"))
+(fs/mkdirSync (node-path/join graphs-dir graph-name) #js {:recursive true})
+(def conn (sqlite-cli/open-db! graphs-dir graph-name))
+(d/transact! conn (sqlite-create-graph/build-db-initial-data "{}"))
+(println "created" (node-path/join graphs-dir graph-name))