logseq/docs/agent-guide/035-logseq-cli-db-worker-deps-cli-decoupling.md

Logseq CLI and db-worker-node deps/cli Decoupling Implementation Plan

Goal: Make logseq-cli behavior independent from old deps/cli regressions while restoring list behavior that regressed after commit 0de3c337e on February 12, 2026.

Architecture: Apply a CLI-scoped decoupling only for the runtime path used by logseq-cli (src/main/logseq/cli/* plus db-worker API path it invokes), and defer non-CLI namespace migration to follow-up work.

Tech Stack: ClojureScript, Datascript, shadow-cljs node-script builds (:logseq-cli and :db-worker-node), babashka test workflow.

Related: Builds on docs/agent-guide/003-db-worker-node-cli-orchestration.md, docs/agent-guide/007-logseq-cli-thread-api-and-command-split.md, and docs/agent-guide/034-db-worker-node-owner-process-management.md.

Developer note (CLI-scoped): The implementation for this plan only migrates the logseq-cli -> db-worker-node -> thread-api runtime path by adding src/main/logseq/cli/common/mcp/tools.cljs. It does not migrate or alter export/Electron/non-CLI namespaces still resolving from deps/cli.

Problem statement

deps/cli is the old CLI codebase, but current runtime paths under src/ still require namespaces from deps/cli, so old CLI commits can silently change new CLI behavior.

Commit 0de3c337e changed deps/cli/src/logseq/cli/common/mcp/tools.cljs and removed fields and filters that new CLI still depends on through db-worker thread-api calls.

Current regressions are reproducible with existing tests.

bb dev:test -v 'logseq.cli.integration-test/test-cli-list-outputs-include-id' currently fails because list items no longer include numeric :id.

bb dev:test -v 'logseq.cli.integration-test/test-cli-add-tags-and-properties-by-id' currently fails because default tag/property lists no longer include built-in entities needed for ID-based add flows.

The dependency path that causes this is shown below.

logseq-cli (src/main/logseq/cli/*)
  -> HTTP invoke to db-worker-node
    -> thread-api methods in frontend.worker.db-core
      -> implementation helper logseq.cli.common.mcp.tools  (currently loaded from deps/cli)

Current dependency inventory

Namespace currently resolved from deps/cli	src/ consumers	Build impact	Status in this plan
logseq.cli.common.mcp.tools	src/main/frontend/worker/db_core.cljs, src/main/logseq/api/db_based/cli.cljs, src/main/logseq/sdk/utils.cljs	:db-worker-node, app API, SDK	In scope now
logseq.cli.common.file	src/main/frontend/worker/export.cljs	:db-worker-node export path	Out of scope now
logseq.cli.common.util	src/main/frontend/extensions/zip.cljs, export handlers	app export and zip features	Out of scope now
logseq.cli.common.export.common	src/main/frontend/handler/export/common.cljs, src/main/frontend/handler/export/html.cljs, src/main/frontend/handler/export/opml.cljs, src/main/frontend/handler/export/text.cljs	app export features	Out of scope now
logseq.cli.common.export.text	src/main/frontend/handler/export/text.cljs	app markdown export	Out of scope now
logseq.cli.common.graph	src/electron/electron/utils.cljs, src/electron/electron/db.cljs, src/electron/electron/handler.cljs	Electron graph directory behavior	Out of scope now
logseq.cli.common.mcp.server	src/electron/electron/server.cljs	Electron MCP HTTP endpoint	Out of scope now
logseq.cli.text-util	src/main/frontend/util/text.cljs	frontend text helpers	Out of scope now

Scope

This plan only changes logseq-cli related runtime behavior.

This plan migrates the logseq-cli -> db-worker-node -> thread-api path where the implementation currently resolves to deps/cli.

In this PR, that means migrating logseq.cli.common.mcp.tools out of deps/cli because it is the thread-api-side implementation used by logseq-cli list/add flows.

This plan does not modify any code under deps/cli.

This plan does not migrate frontend export namespaces, Electron namespaces, or unrelated old CLI modules in deps/cli.

This plan does not redesign CLI command UX or old CLI feature parity, and old CLI under deps/cli remains frozen unless a compatibility fix is required for release safety.

Implementation must follow @test-driven-development, and any unexpected test failure while migrating must follow @clojure-debug before changing behavior.

Testing Plan

I will first lock the current regressions by running the two failing integration tests as baseline checks and recording failure reasons in the PR notes.

I will add focused tests for list data contract behavior so :id, built-in inclusion defaults, and page filtering options are guaranteed independent of old CLI code.

I will run compile checks for both node builds to ensure the CLI path behaves correctly after the targeted namespace move.

I will not include export/Electron migration tests in this PR because those modules are explicitly out of scope.

NOTE: I will write all tests before I add any implementation behavior.

Implementation plan

1. Add a migration checklist section in the PR description that references this document and lists the two known failing integration tests.

2. Run bb dev:test -v 'logseq.cli.integration-test/test-cli-list-outputs-include-id' and confirm it fails before code changes.

3. Run bb dev:test -v 'logseq.cli.integration-test/test-cli-add-tags-and-properties-by-id' and confirm it fails before code changes.

4. Add a focused test file at src/test/logseq/cli/mcp_tools_contract_test.cljs for list-pages, list-tags, and list-properties contract behavior used by new CLI.

5. In that test file, add a case asserting non-expanded list output includes :db/id, :block/title, :block/created-at, and :block/updated-at.

6. In that test file, add a case asserting include-built-in defaults to true and explicitly false excludes built-in tags and properties.

7. In that test file, add a case asserting page list filtering honors include-hidden, include-journal, journal-only, created-after, and updated-after.

8. Add src/main/logseq/cli/common/mcp/tools.cljs by porting the pre-0de3c337e behavior as baseline thread-api implementation and keeping API signatures used by db-core and SDK.

9. Update src/ callsites to resolve the new src/main implementation and keep deps/cli source files untouched.

10. Re-run bb dev:test -v 'logseq.cli.mcp-tools-contract-test' and make it pass with no test skips.

11. Re-run the two integration regressions and make both pass.

12. Keep all files under deps/cli unchanged in this PR.

13. Do not remove logseq/cli from deps.edn in this PR because unrelated frontend and Electron runtime modules still depend on it.

14. Run clojure -M:cljs compile logseq-cli and verify compile success.

15. Run clojure -M:cljs compile db-worker-node and verify compile success.

16. Run bb dev:test -v 'logseq.cli.commands-test/test-list-subcommand-parse' to verify list option parsing remains stable.

17. Run bb dev:test -v 'logseq.cli.integration-test/test-cli-list-outputs-include-id' to verify ID contract restoration end-to-end.

18. Run bb dev:test -v 'logseq.cli.integration-test/test-cli-add-tags-and-properties-by-id' to verify built-in tag/property ID flows end-to-end.

19. Run bb dev:test -v 'logseq.cli.integration-test/test-cli-list-add-show-remove' as a smoke test for normal create/list/show/remove flow.

20. Run bb dev:test -v 'logseq.cli.integration-test/test-cli-query-recent-updated' as a smoke test for list timestamps and query interplay.

21. Run bb dev:lint-and-test before merge to satisfy repository review checklist.

Edge cases to validate during implementation

If created-after or updated-after is an invalid date string, filtering should not crash and should behave as no time filter.

When include-journal is omitted, journals should remain included by default to preserve existing CLI expectations.

When include-built-in is omitted, built-in tags and properties must remain included so ID resolution in add/update flows still works.

Non-expanded list output must contain stable numeric IDs even if UUID and title are present.

Expanded list output must keep UUID string conversion and keep relationship fields (classes, extends, properties) in expected shapes.

Non-CLI frontend export and Electron behavior must remain untouched in this PR.

Open questions requiring clarity

Should we do a second PR for non-CLI namespace migration (export, electron, text-util) immediately after this thread-api decoupling PR, or wait until after release.

Testing Details

The key behavior tests are integration-first and validate user-observable outcomes, not internal helper implementation.

test-cli-list-outputs-include-id verifies that real CLI JSON output includes usable IDs for list operations.

test-cli-add-tags-and-properties-by-id verifies that list output can feed directly into add operations using IDs and complete a write/read roundtrip.

mcp-tools-contract-test verifies option semantics and filtering behavior at the db-worker API boundary to prevent future regressions from unrelated old CLI edits.

Implementation Details

• Keep migration atomic by changing only logseq-cli related runtime pieces in this PR.
• Preserve public function names and argument shapes to minimize callsite churn.
• Restore pre-0de3c337e list semantics for IDs and built-in filtering.
• Do not edit any file under deps/cli; all migration changes must happen in src/ and src/test/.
• Do not change command parsing behavior in src/main/logseq/cli/command/list.cljs unless tests show incompatibility.
• Keep Electron/export/frontend non-CLI require lines unchanged in this PR.
• Treat deps/cli as frozen legacy code for non-CLI modules in this PR.
• Add a short developer note in README.md or docs explaining this PR is CLI-scoped only.
• Use smallest possible commits per namespace group to simplify rollback.
• Ensure all touched files remain ASCII and follow existing formatting conventions.
• Finish with bb dev:lint-and-test and include command outputs in the PR summary.

Decision

This migration will keep logseq.cli.common.* namespace names stable and only move CLI-path runtime implementation needed for logseq-cli.

Namespace renaming will be done in a follow-up PR after decoupling and regression fixes are complete.

---