logseq/docs/agent-guide/025-logseq-cli-builtin-status-priority-queries.md

Logseq CLI Built-in Status/Priority Queries Plan

Goal: Add built-in query names list-status and list-priority that return the available Status/Priority options from a graph. Architecture: Keep the existing logseq-cli → db-worker-node transport and thread-api usage; implement list-status/list-priority via :thread-api/q rather than adding a dedicated thread-api. Tech Stack: ClojureScript, logseq-cli, db-worker-node, Datascript, logseq.db.frontend.property. Related: src/main/logseq/cli/command/query.cljs, src/main/frontend/worker/db_core.cljs, deps/db/src/logseq/db/frontend/property.cljs.

Problem Statement

Logseq CLI’s query built-ins are limited to Datascript queries. Users cannot easily discover valid Status or Priority options for a graph (e.g., TODO/DOING/DONE, Urgent/High/Low) without knowing the property internals or running custom queries. We need simple built-ins that list the closed values configured for Status and Priority.

Non-Goals

• Changing property schemas or defaults.
• Replacing the existing Datascript query flow.
• Adding new UI commands outside query or changing CLI output formats.

Current Behavior (Key Points)

• Built-in queries are defined in built-in-query-specs in src/main/logseq/cli/command/query.cljs and executed via :thread-api/q.
• Status and Priority options are stored as closed values on :logseq.property/status and :logseq.property/priority (see logseq.db.frontend.property/get-closed-property-values).
• There is no CLI helper to list those closed values.

Proposed Changes

1. Use :thread-api/q for closed values

   • Implement list-status/list-priority by issuing a Datascript query via :thread-api/q.
   • Return a vector of maps with :db/ident and :db/id.
   • Use :find with an ellipsis form to return a vector, e.g. :find [(pull ?e [:db/ident :db/id]) ...] (instead of :find (pull ?e [:db/ident :db/id])).

2. Add built-in query names list-status and list-priority

   • Add entries to built-in-query-specs that specify a non-Datascript execution path (e.g., :method/:handler metadata).
   • Wire build-action to create a dedicated action type when these names are used.
   • Update execute-query to call the new thread API and return results as {:result ["TODO" ...]} so existing output formatting works unchanged.

3. Expose built-ins in query list

   • Ensure query list includes the new entries (with doc and inputs: []).
   • Keep existing “custom overrides built-in” semantics.

Implementation Plan

1. db-worker-node API

   • No new thread-api should be added; use :thread-api/q only.

2. CLI built-in wiring

   • Extend built-in-query-specs in src/main/logseq/cli/command/query.cljs:
     • list-status → :property-ident :logseq.property/status
     • list-priority → :property-ident :logseq.property/priority
     • Include :doc and :inputs [].
   • Update normalize-query-entry / find-query handling to preserve the extra metadata.
   • Update build-action:
     • When the built-in includes a :property-ident (or :method), create an action like {:type :query-closed-values :repo ... :property-ident ...}.
   • Update execute-query:
   • Branch on the new action type to call transport/invoke with :thread-api/q and return {:result values} (vector of maps with :db/ident and :db/id).

3. Output and docs

   • No change to formatters; format-query-results already prints vectors.
   • Update CLI docs if needed (e.g., docs/cli/logseq-cli.md) to mention the two built-ins.

Testing Plan

• Unit tests (src/test/logseq/cli/command/query_test.cljs):

  • list-queries includes list-status and list-priority with empty inputs.
  • build-action for --name list-status returns :query-closed-values action with property ident.
  • Custom query overrides built-in name still works.

• db-worker-node tests: no new thread-api, so no additional db-worker-node test needed.

• Integration (src/test/logseq/cli/integration_test.cljs):

  • Start a graph, run logseq query --name list-status / list-priority, assert status ok and a non-empty vector.
  • If stable defaults are known, assert a known value is present; otherwise, seed closed values in the test graph.

Edge Cases

• Property has no closed values → return an empty vector (not an error).
• Closed values may be stored in either :block/title or :logseq.property/value; if :db/ident is absent, the map should still include the key with a nil value.
• Ensure ordering follows :block/order from get-closed-property-values.

Files to Touch

• src/main/frontend/worker/db_core.cljs (no new thread-api)
• src/main/logseq/cli/command/query.cljs (built-in specs, build-action branching, execute-query)
• src/test/logseq/cli/command/query_test.cljs (unit coverage)
• src/test/frontend/worker/db_worker_node_test.cljs or a db-core test (not required for new thread-api)
• src/test/logseq/cli/integration_test.cljs (CLI end-to-end)
• docs/cli/logseq-cli.md (optional docs update)

Open Questions

• Use :thread-api/q to return structured values: {:db/ident .., :db/id ..}.
• Expose list-status/list-priority via query --name only (no dedicated subcommands).

---