forked from d-cloud/d-wiki
57 lines
2.5 KiB
Markdown
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.
|