logseq/docs/agent-guide/056-graph-name-dir-encoding-alignment.md

Align graph dir encoding between logseq-cli and desktop app

Summary

Align logseq-cli, db-worker-node, and desktop app handling of graph dir / graph-name so special characters are encoded and decoded with one shared, reversible contract.

The authoritative contract would be the existing encode-graph-dir-name / decode-graph-dir-name pair in src/main/frontend/worker_common/util.cljc, which is already used by db-worker-node and logseq-cli server-side graph directory resolution.

This plan keeps user-facing graph names unchanged and only aligns their on-disk directory representation.

Background

Current code paths do not agree on how a graph name maps to a graph directory on disk:

• db-worker-node and logseq-cli server/runtime paths use a reversible graph-dir encoding.
• desktop app contains paths that join the raw graph name directly into a filesystem path.
• some Electron and CLI-adjacent helpers still use lossy sanitize-db-name behavior.
• shared graph discovery still contains legacy decoding logic for older naming conventions, but not the current reversible encoding.

This mismatch becomes visible when graph names contain special characters such as /, :, %, ~, or spaces.

Goals

• Use one shared graph-dir encoding/decoding contract across CLI and desktop app.
• Preserve current user-facing graph-name semantics.
• Keep logseq_db_ prefix canonicalization separate from graph-dir encoding.
• Define compatibility behavior for legacy graph directory names.
• Add tests that cover special-character graph names across all affected entry points.

Non-goals

• Redesign the user-visible graph naming model.
• Change the existing logseq_db_ display normalization rules.
• Remove all legacy compatibility in one step without an explicit migration strategy.

Current behavior

Shared reversible encoding already exists

Authoritative implementation today:

• src/main/frontend/worker_common/util.cljc
  • encode-graph-dir-name
  • decode-graph-dir-name

Current behavior:

1. encodeURIComponent is applied.
2. literal ~ is rewritten to %7E.
3. % is rewritten to ~.
4. decoding reverses ~ -> % and then applies decodeURIComponent.

This gives a reversible filesystem-safe directory key without / or \\ path separators.

db-worker-node follows the shared contract

Relevant files:

• src/main/frontend/worker/db_worker_node_lock.cljs
• src/main/frontend/worker/platform/node.cljs
• src/main/frontend/worker/db_worker_node.cljs
• src/main/frontend/worker/graph_dir.cljs

Current behavior:

• repo identity strips one leading logseq_db_ to produce a graph-dir key.
• graph-dir key is encoded with encode-graph-dir-name.
• list-graphs decodes on-disk directory names back to graph-dir keys.
• worker log paths and lock paths are stored under the encoded graph directory.

CLI is partially aligned

Relevant files:

• src/main/logseq/cli/server.cljs
• src/main/logseq/cli/command/core.cljs
• src/main/logseq/cli/command/graph.cljs
• src/main/logseq/cli/common.cljs
• deps/cli/src/logseq/cli/common/graph.cljs
• deps/cli/src/logseq/cli/util.cljs

Current behavior:

• cli.server already uses the same canonical graph-dir path contract as db-worker-node.
• graph display/input normalization strips or restores one logseq_db_ prefix as needed.
• unlink-graph! still derives directory names with sanitize-db-name, which is lossy.
• shared discovery in deps/cli still decodes only older directory naming patterns such as ++ and +3A+.

Desktop app is not aligned

Relevant files:

• src/electron/electron/utils.cljs
• src/electron/electron/db.cljs
• src/electron/electron/handler.cljs
• src/electron/electron/url.cljs
• src/main/frontend/config.cljs

Current behavior:

• electron.utils/get-graph-dir joins the raw graph name into the graph path after db-prefix stripping.
• if the graph name contains /, the resulting path becomes nested directories.
• electron.db still uses sanitize-db-name in some db path creation logic.
• frontend local-dir helpers also treat graph name as a raw path segment.

Problem statement

The same logical graph name can map to different on-disk paths depending on which subsystem touches it:

• reversible encoded path in db-worker-node
• raw path join in Electron/frontend
• lossy underscore replacement in sanitize-based helpers
• legacy decode-only behavior in shared graph discovery

As a result:

• a graph may be listable but not removable
• a graph may be resolvable in CLI but not in desktop app
• a graph name containing / may accidentally create path nesting in one flow but not another
• existing tests do not enforce cross-subsystem parity

Proposed contract

1. Separate graph identity from graph directory representation

The plan would explicitly distinguish:

• graph-name / repo: user-facing identifier, subject to existing logseq_db_ canonicalization rules
• graph-dir key: graph-name with exactly one leading db prefix stripped
• encoded graph-dir: on-disk directory name produced only by encode-graph-dir-name

This separation would make it clear that special-character handling belongs to the graph-dir layer, not the user-facing name layer.

2. Make the db-worker-node contract authoritative

The repository would standardize on:

• repo -> graph-dir key: strip one leading logseq_db_
• graph-dir key -> encoded graph-dir: encode-graph-dir-name
• encoded graph-dir -> graph-dir key: decode-graph-dir-name

Any code path that needs an on-disk db graph directory would route through this contract rather than reimplementing path logic.

3. Keep user-visible graph names unchanged

The plan would preserve current user-visible behavior:

• CLI graph names remain prefix-free for display and config storage where already intended.
• desktop app continues to display logical graph names, not encoded directory names.
• URL-level graph identification continues to resolve to logical graph names, not on-disk encoded names.

Proposed code changes

A. Consolidate path-authoritative helpers

Add or reuse one shared helper layer for:

• converting repo to graph-dir key
• converting graph-dir key to encoded graph directory
• converting repo directly to on-disk graph directory path

Target files likely involved:

• src/main/frontend/worker/graph_dir.cljs
• src/main/frontend/worker/db_worker_node_lock.cljs
• src/electron/electron/utils.cljs
• src/main/frontend/config.cljs
• deps/cli/src/logseq/cli/util.cljs

Expected outcome:

• no raw path join for logical graph names in path-authoritative code
• no duplicate graph-dir encoding implementations

B. Align Electron graph-dir resolution

Replace raw graph path derivation in Electron with the shared encoded graph-dir contract.

Target files:

• src/electron/electron/utils.cljs
• src/electron/electron/handler.cljs
• src/electron/electron/db.cljs

Expected outcome:

• desktop app resolves the same on-disk graph dir as db-worker-node
• graph names containing /, :, %, ~, or spaces behave predictably
• sanitize-db-name is no longer used for authoritative db graph-dir mapping

C. Align CLI remove/unlink behavior

Update CLI removal/unlink flows to resolve graph directories via the same encoded contract used by list/start/lock behavior.

Target file:

• src/main/logseq/cli/common.cljs

Expected outcome:

• a graph that can be listed or switched to can also be removed through the same path mapping

D. Align shared graph discovery

Update shared discovery helpers so current encoded graph dirs are decoded correctly, while preserving deliberate support for legacy names where needed.

Target file:

• deps/cli/src/logseq/cli/common/graph.cljs

Expected outcome:

• desktop/CLI discovery would recognize encoded graph dirs produced by current db-worker-node logic
• legacy decode branches would be explicitly documented as compatibility behavior

E. Audit frontend local-dir helpers

Review helpers that expose graph-related directories to ensure they are either:

• display-only helpers, or
• path-authoritative helpers using the shared encoded contract

Target file:

• src/main/frontend/config.cljs

Expected outcome:

• no ambiguous helper remains that appears safe for filesystem use while still using raw graph names

Compatibility and migration

This plan should explicitly decide how to handle already-existing graph directories created by older logic.

Option 1: Read legacy names, write canonical encoded names

Behavior:

• discovery accepts legacy directory names and current encoded names
• all newly created or rewritten paths use the canonical encoded form
• optional one-time migration may rename legacy directories

Pros:

• safer rollout
• less risk of immediately losing access to existing graphs

Cons:

• mixed formats may coexist temporarily

Option 2: Auto-migrate on access

Behavior:

• when a legacy graph directory is detected, code renames it to the canonical encoded path before continuing

Pros:

• converges quickly to one format

Cons:

• higher operational risk
• rename behavior must be designed carefully for active workers and lock files

Option 3: Strict cutover

Behavior:

• only encoded graph dirs are supported after the change

Pros:

• simplest long-term contract

Cons:

• too risky without explicit migration tooling

Recommended direction

Prefer Option 1 for the first rollout:

• read compatibility for legacy directory names
• canonical writes to encoded graph dirs
• add explicit migration follow-up only after parity tests pass

Test plan

Unit tests

Extend or add tests for:

• src/test/frontend/worker/worker_common_util_test.cljs
• src/test/frontend/worker/db_worker_node_lock_test.cljs
• src/test/logseq/cli/server_test.cljs
• src/test/logseq/cli/common/graph_test.cljs
• Electron-specific tests if available for graph-dir resolution

Special-character test matrix

All subsystems should use the same examples:

• foo/bar
• a:b
• space name
• 100% legit
• til~de
• mix/of:many %chars~here

Behavior to verify

1. encode/decode roundtrip is lossless
2. CLI list-graphs returns the same logical graph name that was encoded on disk
3. CLI switch/remove resolve the same graph directory
4. desktop app resolves the same graph directory as CLI/db-worker-node
5. graph names remain user-visible without encoded substitutions
6. legacy discovery behavior remains intentional and documented

Missing coverage today

The repository currently appears to lack end-to-end parity tests for:

• CLI create/switch/remove with special-character graph names
• Electron graph-name -> graph-dir resolution with special characters
• desktop and CLI agreement on one on-disk graph directory for the same logical graph

Rollout sequence

1. Make the shared graph-dir contract explicit in code and docs.
2. Update Electron path-authoritative helpers to use encoded graph dirs.
3. Update CLI unlink/remove behavior to use the same mapping.
4. Update shared graph discovery for encoded graph dirs and legacy compatibility.
5. Add parity tests across worker, CLI, and desktop-related helpers.
6. Evaluate whether legacy directory migration should be a separate follow-up.

Risks

• Existing graphs may already exist under lossy or raw directory naming rules.
• Desktop-specific compatibility code may rely on current path layout assumptions.
• URL/deeplink flows may resolve graph identifiers separately from filesystem mapping and should not accidentally expose encoded names to users.
• Removing sanitize-db-name from authoritative paths may surface hidden assumptions in older db bootstrap code.

Open questions

1. Should legacy raw/sanitized graph directories remain writable, or only readable?
2. Should migration happen automatically, manually, or in a later dedicated change?
3. Which helper should become the single exported entry point for graph-name -> on-disk graph-dir path resolution?
4. Should docs/cli/logseq-cli.md be updated in the same change to clarify that on-disk graph directories are encoded, not always literal graph names?

Expected files to change in implementation

Likely implementation targets:

• src/main/frontend/worker_common/util.cljc
• src/main/frontend/worker/graph_dir.cljs
• src/main/frontend/worker/db_worker_node_lock.cljs
• src/main/logseq/cli/server.cljs
• src/main/logseq/cli/common.cljs
• deps/cli/src/logseq/cli/common/graph.cljs
• deps/cli/src/logseq/cli/util.cljs
• src/electron/electron/utils.cljs
• src/electron/electron/db.cljs
• src/electron/electron/handler.cljs
• src/main/frontend/config.cljs
• related tests under src/test/

Acceptance criteria

This plan would be complete when:

• one shared graph-dir encoding contract is identified as authoritative
• all affected subsystems and files are enumerated
• compatibility strategy for legacy graph directories is documented
• a concrete test matrix for special-character graph names is defined
• the plan preserves current user-facing graph-name semantics while aligning on-disk graph-dir behavior