# 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.