wdb/docs/language-decision.md
2026-05-28 19:02:16 +08:00

57 lines
2.5 KiB
Markdown

# d-wiki CLI language decision
## Decision
Use Python for the first implementation of `d-wiki`.
The CLI is a local knowledge retrieval component that needs predictable file
system traversal, Markdown/Sphinx source parsing, YAML metadata, BM25 ranking,
JSON output, and straightforward integration with `robogo_assistant_service`.
Python is the lower-risk choice for this first version because the surrounding
service code and tests are already Python, and the implementation intentionally
avoids qmd, embeddings, and Node-specific runtime requirements.
## Python pros
- Matches the existing `robogo_assistant_service` stack, test style, and local
developer workflow.
- Strong standard library support for CLI parsing, paths, subprocess-friendly
JSON output, dataclasses, and text processing.
- Easy to keep dependency-light; the current package has no required runtime
dependencies and can optionally use PyYAML when present.
- Good fit for future retrieval upgrades such as ranking experiments,
evaluation scripts, corpus analysis, and possible embedding backends.
- Lower integration friction for service tests that call the CLI from Python.
## Python cons
- Single-file executable distribution is less natural than Node/npm CLIs unless
extra packaging tools are introduced.
- Startup can be slower than a bundled JS runtime for very small commands,
though this is not a bottleneck for local document search.
- Type safety depends on discipline and tools rather than the language runtime.
## TypeScript pros
- Excellent CLI packaging through npm and strong cross-platform installation
conventions for JS-heavy teams.
- Static types are first-class and make API shape evolution explicit.
- Easier future alignment if `d-wiki` becomes a qmd-native or MCP-first Node
package.
## TypeScript cons
- Adds a second runtime stack beside the Python service for the first version.
- The plan explicitly avoids qmd/Node runtime complexity in v1; starting with
TypeScript would pull the project toward the complexity it is trying to defer.
- Requires build tooling, lockfiles, module-format decisions, and generated
output conventions before the retrieval logic itself benefits from them.
- Python service integration would still happen through subprocess JSON, so the
main service does not gain much from a TypeScript implementation today.
## Revisit triggers
Reconsider TypeScript if `d-wiki` becomes a distributed npm CLI, adopts qmd as
the default backend, ships an MCP server primarily for Node-based agents, or
needs to share substantial code with a TypeScript UI or SDK.