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

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