mirror of
https://github.com/Kaelio/ktx.git
synced 2026-07-13 11:22:11 +02:00
feat(cli): shell completion for commands, flags, and entity names (#244)
* feat(completion): complete known argument values
* fix(completion): hide Commander-hidden subcommands from completions
Replace the `__`-prefix name heuristic with Commander's `_hidden` flag so
internal subcommands registered with { hidden: true } (e.g. `mcp serve-internal`)
are excluded from completions, mirroring `ktx --help`.
* test: cover wiki and sl read command routing
* test: cover raw wiki and sl reads
* feat: add wiki read command
* feat: add sl read command
* feat: complete read command entity names
* docs: document wiki and sl read commands
* test: include read commands in command tree
* feat(sl): read and validate unique sources by name
* feat(sl): make read and validate connection id optional
* fix(completion): dedupe semantic source names
* docs(sl): document connection-optional read and validate
* fix(sl): require connection id for query command
* docs(sl): clarify query connection requirement
* fix(completion): don't resolve option values as subcommands
resolveCommand skipped flag tokens but not the value consumed by a
value-taking option in the `--flag value` form, so a connection id like
`query` was matched as the `sl query` subcommand and yielded no `sl`
completions. Track value-taking options and skip their consumed value
before matching subcommands.
* test(telemetry): assert first-run notice via TELEMETRY_NOTICE constant
CI (which tests this branch merged with main) failed because #243 changed
the first-run notice wording in identity.ts (dropped "anonymous") but left
this test grepping for the old literal 'ktx collects anonymous usage data',
so indexOf returned -1. Assert against the exported TELEMETRY_NOTICE
constant instead so the test tracks the source of truth and cannot drift
when the notice text changes again.
This commit is contained in:
parent
c196d1f192
commit
d320d54ab2
28 changed files with 1596 additions and 54 deletions
|
|
@ -1,21 +1,24 @@
|
|||
---
|
||||
title: "ktx wiki"
|
||||
description: "List or search wiki pages."
|
||||
description: "List, search, or read wiki pages."
|
||||
---
|
||||
|
||||
List and search wiki pages in your **ktx** project. Wiki pages are Markdown
|
||||
documents that capture business definitions, rules, and gotchas. Agents search
|
||||
them for context when answering questions about your data.
|
||||
List, search, and read wiki pages in your **ktx** project. Wiki pages are
|
||||
Markdown documents that capture business definitions, rules, and gotchas.
|
||||
Agents search them for context when answering questions about your data.
|
||||
|
||||
## Command signature
|
||||
|
||||
```bash
|
||||
ktx wiki [options] [query...]
|
||||
ktx wiki [options] [query...] # list (bare) or search (with query)
|
||||
ktx wiki read <key>
|
||||
```
|
||||
|
||||
- Bare `ktx wiki` lists local wiki pages.
|
||||
- `ktx wiki <query...>` searches local wiki pages (multi-word queries are
|
||||
joined with a space).
|
||||
- `ktx wiki <query...>` searches local wiki pages. Multi-word queries are
|
||||
joined with a space.
|
||||
- `ktx wiki read <key>` prints the whole Markdown file for one wiki page,
|
||||
including YAML frontmatter.
|
||||
|
||||
Edit the Markdown files under `wiki/` directly, or ingest source content with
|
||||
`ktx ingest`, when you need to add or update wiki knowledge.
|
||||
|
|
@ -50,6 +53,9 @@ ktx wiki "monthly recurring revenue"
|
|||
# Search wiki pages as JSON
|
||||
ktx wiki "monthly recurring revenue" --json --limit 10
|
||||
|
||||
# Print the exact Markdown file for a known page key
|
||||
ktx wiki read revenue-definitions
|
||||
|
||||
# Print search results as TSV
|
||||
ktx wiki "monthly recurring revenue" --output plain
|
||||
|
||||
|
|
@ -62,8 +68,10 @@ ktx --debug wiki "monthly recurring revenue" --json
|
|||
Wiki commands print clack-style pretty output in a TTY and TSV-style plain
|
||||
output when requested. JSON output wraps the items with a command metadata
|
||||
envelope. Search results include `matchReasons` and `lanes` metadata so you can
|
||||
see whether lexical, token, or semantic search contributed to the ranking. Open
|
||||
the matching Markdown files directly when you need the full page contents.
|
||||
see whether lexical, token, or semantic search contributed to the ranking. Use
|
||||
`ktx wiki read <key>` when you need the full page contents. Read output is the
|
||||
exact Markdown file stored on disk, including YAML frontmatter, and is not
|
||||
wrapped in pretty, plain, or JSON formatting.
|
||||
Pretty search output shows `#1`, `#2`, and later rank badges for the displayed
|
||||
results. Plain and JSON output keep the raw `score` value, which is a ranking
|
||||
score rather than a percentage.
|
||||
|
|
@ -121,4 +129,4 @@ stays machine-readable:
|
|||
| Error | Cause | Recovery |
|
||||
|-------|-------|----------|
|
||||
| Search returns no results | The query terms do not match summaries, tags, or content, and the semantic lane is unavailable or has no positive matches | Run with `--debug`, check the semantic lane status, retry with business synonyms, then create a page if the knowledge is missing |
|
||||
| A page is missing | No Markdown file exists for that business context | Add a file under `wiki/` or run `ktx ingest <connectionId>` |
|
||||
| A page is missing | No Markdown file exists for that business context or `ktx wiki read <key>` used the wrong key | Run `ktx wiki <query>` to find the page key, then retry `ktx wiki read <key>` |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue