feat(cli): add qmd query (1)

docs/agent-guide/logseq-cli/011-qmd-search.md

@@ -0,0 +1,70 @@
+# QMD Search CLI Implementation Plan
+
+## Goal
+
+Add `logseq qmd init` and `logseq qsearch` so CLI users can search DB graph Markdown Mirror files through QMD and map search hits back to Logseq block entities.
+
+## Architecture
+
+- Keep the QMD integration in the CLI process.
+- Call `qmd` as an external executable through Node child process APIs with argument vectors.
+- Reuse db-worker-node startup and transport helpers.
+- Reuse the existing `:thread-api/markdown-mirror-regenerate` API for mirror generation.
+- Reuse the existing `:thread-api/pull` API for entity lookup.
+- Do not add a new thread API for this feature.
+
+## Public Interface
+
+`logseq qmd init --graph <graph> [--index <name>] [--collection <name>]`
+
+- Verify that `qmd` is executable.
+- Regenerate Markdown Mirror for the selected graph.
+- Resolve the mirror directory as `<root-dir>/graphs/<encoded-repo>/mirror/markdown`.
+- Initialize the QMD collection with `qmd collection add <mirror-dir> --name <collection> --mask "**/*.md"`.
+- If the collection already points at the same mirror directory, run `qmd update`.
+- If the collection name points at a different path, fail fast.
+
+`logseq qsearch <query> --graph <graph> [-n <limit>] [--index <name>] [--collection <name>] [--no-rerank]`
+
+- Run `qmd query <query> --json -c <collection> -n <limit>`.
+- Parse noisy QMD stdout defensively.
+- Extract block ids from Markdown Mirror comments matching `<!-- id: 123 -->`.
+- Pull entities through `:thread-api/pull`.
+- Deduplicate ids in QMD rank order.
+- Return Logseq list-style output plus `missing-ids` for stale QMD results.
+
+Default collection names use `logseq-<graph-slug>-<repo-hash8>` to avoid collisions between graphs with similar display names.
+
+## Data Flow
+
+```mermaid
+flowchart LR
+  A["logseq qmd init"] --> B["db-worker-node"]
+  B --> C["markdown-mirror-regenerate"]
+  C --> D["Markdown Mirror directory"]
+  D --> E["qmd collection add/update"]
+
+  F["logseq qsearch"] --> G["qmd query --json"]
+  G --> H["Extract block id comments"]
+  H --> I["thread-api/pull"]
+  I --> J["List-style CLI output"]
+```
+
+## Implementation Tasks
+
+- Add `src/main/logseq/cli/command/qmd.cljs` for command entries, action builders, QMD process execution, collection initialization, QMD JSON parsing, id extraction, and qsearch normalization.
+- Wire `qmd init` and `qsearch` into `src/main/logseq/cli/commands.cljs`.
+- Show `qmd` in utility help and `qsearch` in graph inspect/search help.
+- Format `:qmd-init` and `:qsearch` in `src/main/logseq/cli/format.cljs` for human, JSON, and EDN output.
+- Add unit tests for command entries, graph requirements, default collection names, mirror path derivation, QMD executable checks, collection create/update/mismatch handling, noisy JSON parsing, block id extraction, dedupe order, missing ids, and entity pull calls.
+- Add parser tests for `qmd init`, `qsearch`, help output, positional query handling, and invalid option behavior.
+- Add format tests for human table output and JSON/EDN payload stability.
+- Add a CLI E2E case with a fake `qmd` executable on `PATH` so the test does not depend on local QMD models, embeddings, or network access.
+
+## Verification
+
+- Run focused unit tests for `logseq.cli.command.qmd-test`, `logseq.cli.commands-test/test-qmd-and-qsearch-parse`, and qsearch/qmd format tests.
+- Run `bb dev:lint-and-test`.
+- Run `bb -f cli-e2e/bb.edn build`.
+- Run `bb -f cli-e2e/bb.edn test --skip-build`.
+- Review the finished diff with `logseq-review-workflow`, applying common, Clojure/CLJS, promesa/Node process, babashka CLI, shadow-cljs Node, logseq-cli, and search-indexing rules.