forked from d-cloud/d-wiki
2.5 KiB
2.5 KiB
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_servicestack, 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-wikibecomes 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.