logseq/docs/agent-guide/012-logseq-cli-graph-storage.md

Logseq CLI Graph Storage Plan

Context

logseq-cli and db-worker-node currently store CLI-managed graphs under ~/.logseq/db-worker/ and use per-graph directories named like .logseq-pool-<graph-name>/ (with partial encoding). This plan captures the non-functional updates requested:

1. Rename ~/.logseq/db-worker/ to ~/logseq/cli-graphs/ for CLI-managed graphs.
2. Rename per-graph directory format from .logseq-pool-<graph-name>/ to <graph-name>/.
3. Ensure graph names that are not valid directory names are encoded, and decoding is symmetric when reading/listing.

Goals

• Move CLI graph storage to ~/logseq/cli-graphs by default.
• Use a clean per-graph directory name equal to the (encoded) graph name, without . prefix or logseq-pool- prefix.
• Provide a reversible encode/decode for graph names so list/read operations reconstruct the original graph name.
• CLI commands and outputs should hide the internal logseq_db_ prefix; user-facing graph names strip that db prefix.
• Maintain db-worker-node functionality (locks/logs/kv-store) with the new paths.

Non-goals

• Changing Electron or browser-based db graph storage (~/logseq/graphs) or OPFS behavior.
• Changing db schema or sqlite storage format.
• Changing db-worker-node API semantics.

Current Behavior (Key References)

• CLI default data dir is ~/.logseq/db-worker: src/main/logseq/cli/config.cljs.
• db-worker-node default data dir is ~/.logseq/db-worker: src/main/frontend/worker/db_worker_node.cljs, src/main/frontend/worker/db_worker_node_lock.cljs, src/main/frontend/worker/platform/node.cljs.
• Per-graph directory currently .logseq-pool-<sanitized>:
  • frontend.worker-common.util/get-pool-name returns logseq-pool-<sanitized>: src/main/frontend/worker_common/util.cljc.
  • repo-dir uses "." + pool-name in CLI server, db-worker-node lock, and node platform: src/main/logseq/cli/server.cljs, src/main/frontend/worker/db_worker_node_lock.cljs, src/main/frontend/worker/platform/node.cljs.
• Current graph decoding in list operations reverses only +3A+ and ++ (file-based graphs); other characters are not reversible: src/main/logseq/cli/server.cljs, src/main/frontend/worker/platform/node.cljs.

Proposed Approach

1) New default data dir

• Change default data dir for CLI and db-worker-node from ~/.logseq/db-worker to ~/logseq/cli-graphs.
• Update help text and any user-facing docs mentioning the old default.

2) New per-graph directory naming

• Replace .logseq-pool-<graph-name>/ with <encoded-graph-name>/.
• Remove the leading dot and logseq-pool- prefix entirely for CLI-managed graphs.

3) Reversible graph name encoding

• Introduce a shared encode/decode pair for graph directory names that is bijective for all graph names.
• The encoding must avoid path separators and other invalid characters (esp. /, \, : on Windows).
• Suggested approach (reversible and simple):
  • Encode: apply encodeURIComponent to the graph name, then replace % with a safe delimiter (e.g. ~) to keep filenames readable and avoid % edge cases.
  • Decode: reverse the delimiter replacement, then decodeURIComponent.
• Provide helper functions in a shared place (e.g. frontend.worker-common.util or a new shared CLI/worker helper) so CLI server, db-worker-node lock, and node platform list all use the same encode/decode logic.

Implementation Steps

1. Add encode/decode helpers

   • Add new helpers for reversible graph name <-> directory name.
   • Update get-pool-name or replace its usage for CLI/db-worker-node paths.
   • Files: src/main/frontend/worker_common/util.cljc, potentially deps/cli/src/logseq/cli/common/graph.cljs.

2. Update data dir defaults

   • Change defaults to ~/logseq/cli-graphs in:
     • src/main/logseq/cli/config.cljs
     • src/main/logseq/cli/server.cljs
     • src/main/frontend/worker/db_worker_node_lock.cljs
     • src/main/frontend/worker/db_worker_node.cljs (help text)
     • src/main/frontend/worker/platform/node.cljs
   • Update any CLI docs/tests that reference db-worker as default.

3. Update repo-dir/path derivation

   • Replace "." + pool-name usage with new <encoded-graph-name> directory naming.
   • Update list-graphs and list-servers to decode from new directory names.
   • Files: src/main/logseq/cli/server.cljs, src/main/frontend/worker/db_worker_node_lock.cljs, src/main/frontend/worker/platform/node.cljs.

4. Tests & verification

   • Update CLI integration tests that construct temp dirs named db-worker* to match new defaults or explicitly pass --data-dir.
   • Update db-worker-node tests to use new naming and to validate encode/decode.
   • Ensure bb dev:lint-and-test passes.

Open Questions

• The new encoding is CLI and db-worker-node only (no Electron changes).

Rollout Notes

• This is a filesystem layout change. Include release notes and ensure users can override via --data-dir.
• Provide a one-time warning if old layout is detected and not migrated.