@geml/logseq-sync 2.0.2 → 2.0.4

package/README.md

@@ -21,7 +21,7 @@ Two settings, and only the first one usually needs touching:
   database dump, in a folder you chose
 - 🔁 **Continuous, not one-shot** — edit in Logseq, and seconds later the file
   on disk has caught up
-- ↩️ **A way back** — `geml-sync restore` imports the vault into a graph,
+- ↩️ **A way back** — `logseq-sync restore` imports the vault into a graph,
   merging by block uuid. Files you can read are worth more when they are also
   files you can return
 - 🌿 **Git if you want it** — point the vault at a repository and every sync is
@@ -68,7 +68,7 @@ no git, no shell (verified against the 2.0.1 app bundle). So the in-app plugin
   dirty-marker file through the plugin storage API;
 - **show** the last sync result in the toolbar (`⇄`) and command palette.
 
-Everything with side effects lives in the **watcher** (`watcher/bin/geml-sync.mjs`),
+Everything with side effects lives in the **watcher** (`watcher/bin/logseq-sync.mjs`),
 built on Logseq's own EDN export. It reacts to the marker file
 immediately (interval polling stays on as a fallback), writes only the files
 that actually changed — so `git diff` is never noise — commits with a pathspec
@@ -82,18 +82,19 @@ Real output, real DB graph (exported with the official CLI, validated by
 `logseq validate`):
 
 ```text
-$ node watcher/bin/geml-sync.mjs geml-spike ~/vault-demo --git-commit --signal <storage>/geml-sync-dirty.json
-Starting GEML Sync: Graph "geml-spike" ➔ ~/vault-demo
-Git auto-commit: enabled (scoped to target paths)
-[19:29:14] Synced: 8 written, 0 unchanged.
-  Git: [master (root-commit) 9cc348c] logseq-geml: sync graph "geml-spike"
+$ logseq-sync geml-spike ~/vault-demo --once --git-commit --no-signal
+Sync Vault with GEML: graph "geml-spike" ➔ ~/vault-demo
+  export via  @logseq/cli, opening the graph file directly — close the graph in Logseq first
+  git         auto-commit on, scoped to the vault
+[10:15:28] Synced: 8 written, 0 unchanged.
+  Git: [master (root-commit) 2854063] logseq-geml: sync graph "geml-spike"
  9 files changed, 142 insertions(+)
  create mode 100644 graph.geml
  create mode 100644 pages/contents.geml
  ...
 
-$ node watcher/bin/geml-sync.mjs geml-spike ~/vault-demo --git-commit --signal ...   # run again
-[19:29:55] Graph is up-to-date (0 written, 8 unchanged).
+$ logseq-sync geml-spike ~/vault-demo --once --git-commit --no-signal   # run again
+[10:15:31] Graph is up-to-date (0 written, 8 unchanged).
 ```
 
 ## Setup
@@ -108,7 +109,7 @@ GEML* → **Vault folder**. Any folder you like — `~/logseq-vault`, a director
 inside a repository you already keep, one your backup tool already watches. It
 is created if it does not exist, `~` means your home directory, and `restore`
 reads the vault back from the same place. There is deliberately **no default**:
-left empty, `geml-sync` asks you for a folder rather than picking one for you.
+left empty, `logseq-sync` asks you for a folder rather than picking one for you.
 
 That is the folder the files are written **into**; the graph they come **from**
 is detected, and you do not name it.
@@ -143,8 +144,8 @@ found and what is missing, and exits non-zero when the setup cannot sync:
 
 | | |
 |---|---|
-| `geml-sync <vault-dir>` | vault here instead of in the plugin settings |
-| `geml-sync <graph> <vault-dir>` | both explicitly |
+| `logseq-sync <vault-dir>` | vault here instead of in the plugin settings |
+| `logseq-sync <graph> <vault-dir>` | both explicitly |
 | `--graph <name>` | pick the graph — needed when several are open |
 | `--once` | sync once and exit, instead of watching |
 | `--git-commit` | commit, creating the vault repository if there is none |
@@ -155,11 +156,11 @@ found and what is missing, and exits non-zero when the setup cannot sync:
 | `--app-cli <path>` | a Logseq CLI the search did not find |
 | `--signal <file>` / `--no-signal` | the plugin bridge, or none |
 
-### Going back: `geml-sync restore`
+### Going back: `logseq-sync restore`
 
 ```sh
-geml-sync restore                 # rehearse: says what it would import, writes nothing
-geml-sync restore --yes           # take a Logseq backup, then import the vault
+logseq-sync restore                 # rehearse: says what it would import, writes nothing
+logseq-sync restore --yes           # take a Logseq backup, then import the vault
 ```
 
 The vault imports into the graph by block uuid, so an edit lands in place
@@ -185,7 +186,7 @@ graph the app does **not** have open, and on Node 24 it needs a
 mkdir logseq-cli && cd logseq-cli && npm init -y
 npm pkg set overrides.better-sqlite3=12.11.1
 npm i @logseq/cli
-# then: LOGSEQ_CLI_DIR=$PWD geml-sync --no-app-cli …
+# then: LOGSEQ_CLI_DIR=$PWD logseq-sync --no-app-cli …
 ```
 
 `--api-server-token` (or `LOGSEQ_API_SERVER_TOKEN`) routes that fallback
@@ -265,7 +266,7 @@ threads are
 
 ```
 core/      converter (mapping.mjs), sync engine, bridge.mjs (the signal/status file contract)
-watcher/   the geml-sync CLI and its end-to-end tests — published to npm as @geml/logseq-sync
+watcher/   the logseq-sync CLI and its end-to-end tests — published to npm as @geml/logseq-sync
 plugin/    the in-app half (this package.json is the Logseq plugin manifest)
 ```
 

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,13 +1,13 @@
 {
   "name": "@geml/logseq-sync",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "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"
+    "logseq-sync": "watcher/bin/logseq-sync.mjs"
   },
   "files": [
     "core/src",
@@ -44,7 +44,7 @@
   ],
   "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/geml-sync.mjs",
+    "sync": "node watcher/bin/logseq-sync.mjs",
     "build:plugin": "node plugin/build.mjs"
   },
   "dependencies": {

package/watcher/bin/{geml-sync.mjs → logseq-sync.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-// geml-sync — a Logseq DB graph ➔ a Git-friendly folder of readable GEML files.
-// The full usage is the USAGE constant below, printed by `geml-sync --help`.
+// logseq-sync — a Logseq DB graph ➔ a Git-friendly folder of readable GEML files.
+// The full usage is the USAGE constant below, printed by `logseq-sync --help`.
 
 import { execFileSync } from "node:child_process";
 import {
@@ -23,13 +23,13 @@ import {
 
 const PLUGIN_TITLE = "Sync Vault with GEML";
 
-const USAGE = `geml-sync — a Logseq DB graph ➔ a Git-friendly folder of readable GEML files.
+const USAGE = `logseq-sync — a Logseq DB graph ➔ a Git-friendly folder of readable GEML files.
 
 Usage:
-  geml-sync [vault-dir] [flags]          vault-dir defaults to the plugin's setting
-  geml-sync <graph> <vault-dir> [flags]  explicit form, when you have several graphs
-  geml-sync doctor                       report what was detected and what is missing
-  geml-sync restore [vault-dir]          vault ➔ graph. Rehearses; --yes performs it,
+  logseq-sync [vault-dir] [flags]          vault-dir defaults to the plugin's setting
+  logseq-sync <graph> <vault-dir> [flags]  explicit form, when you have several graphs
+  logseq-sync doctor                       report what was detected and what is missing
+  logseq-sync restore [vault-dir]          vault ➔ graph. Rehearses; --yes performs it,
                                          taking a graph backup first (--no-backup to skip)
 
 Whatever can be worked out, is: the CLI that ships inside the desktop app,
@@ -135,8 +135,10 @@ for (let i = 0; i < args.length; i++) {
   } else if (arg === "--api-server-token") {
     needValue(i, "--api-server-token");
     flags.apiServerToken = args[++i];
-  } else if (arg.startsWith("--")) {
-    console.error(`Error: Unknown flag "${arg}". Run \`geml-sync --help\` for usage.`);
+  } else if (arg.startsWith("-")) {
+    // One dash included: "-graph demo" once sailed through as a graph literally
+    // named "-graph" and a vault named "demo" — a typo must stop, not sync.
+    console.error(`Error: Unknown flag "${arg}". Run \`logseq-sync --help\` for usage.`);
     process.exit(2);
   } else if (subcommand === null && positional.length === 0 && (arg === "doctor" || arg === "restore")) {
     subcommand = arg;
@@ -263,7 +265,7 @@ if (positional.length >= 2) {
   if (isGraphName) {
     console.error(
       `Error: "${only}" is the name of a graph, not a vault directory. ` +
-        `Write the destination too — geml-sync ${only} <vault-dir> — or select it with --graph ${only}.`
+        `Write the destination too — logseq-sync ${only} <vault-dir> — or select it with --graph ${only}.`
     );
     process.exit(2);
   }
@@ -293,7 +295,7 @@ function resolveVaultOrExit() {
   if (vaultRaw) return resolve(expandHome(vaultRaw));
   console.error(
     `Error: no vault directory. Set it in Logseq — Settings → Plugins → ${PLUGIN_TITLE} → ` +
-      `"Vault folder" — or pass one: geml-sync <vault-dir>.`
+      `"Vault folder" — or pass one: logseq-sync <vault-dir>.`
   );
   process.exit(2);
 }
@@ -379,12 +381,12 @@ function doctor() {
   const sig = resolveSignalPath();
   rows.push(`${sig ? "  ok  " : " note "} ${"bridge".padEnd(14)} ${sig ?? "no plugin storage dir; interval polling only"}`);
 
-  console.log(`${PLUGIN_TITLE} — geml-sync doctor\n`);
+  console.log(`${PLUGIN_TITLE} — logseq-sync doctor\n`);
   console.log(rows.join("\n"));
   console.log(
     blocked
       ? "\nNot ready: fix the MISS lines above."
-      : "\nReady. Run `geml-sync` with no arguments to start syncing."
+      : "\nReady. Run `logseq-sync` with no arguments to start syncing."
   );
   process.exit(blocked ? 1 : 0);
 }
@@ -395,7 +397,10 @@ if (subcommand === "doctor") doctor();
 graphName = resolveGraphOrExit();
 
 // Validate graph name to prevent command/path injection
-if (!/^[a-zA-Z0-9_.-]+$/.test(graphName)) {
+// The first character must not be a dash or a dot: the name travels as argv
+// into the exporting CLI, where a leading dash reads as a flag ("-graph"
+// arrived here as a real user typo for --graph), and "." / ".." read as paths.
+if (!/^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/.test(graphName)) {
   console.error(`Error: Invalid graph name "${graphName}". Only alphanumeric characters, hyphens, and underscores are allowed.`);
   process.exit(2);
 }
@@ -476,9 +481,19 @@ function runLogseqCli(...cmdArgs) {
     });
   }
 
-  // Fallback to npx (executable npx.cmd on Windows, npx on Unix) without shell: true
-  const npxCmd = process.platform === "win32" ? "npx.cmd" : "npx";
-  return execFileSync(npxCmd, ["-y", "@logseq/cli", ...cmdArgs], {
+  // On Windows the npx fallback is an instruction, not a spawn: Node refuses
+  // to run a .cmd without a shell (CVE-2024-27980), and routing a user-typed
+  // graph name through cmd.exe to get around that is how injection happens.
+  // Every prior attempt died as `spawnSync npx.cmd EINVAL`, once every poll.
+  if (process.platform === "win32") {
+    throw new Error(
+      "@logseq/cli is not installed where I can see it. Install it once\n" +
+      "  (mkdir logseq-cli && cd logseq-cli && npm init -y && npm i @logseq/cli)\n" +
+      "and point LOGSEQ_CLI_DIR at that directory — or pass --app-cli <path>\n" +
+      "to the desktop app's CLI."
+    );
+  }
+  return execFileSync("npx", ["-y", "@logseq/cli", ...cmdArgs], {
     cwd: cliCwd,
     encoding: "utf8",
     shell: false,