GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
toolbox: the documented `npm install kcmd` resolves to an unrelated package, and the enrichment CLI is named two ways
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
Two README accuracy items in `toolbox/`, both of which send a reader somewhere
that does not exist.
**1. `npm install kcmd` installs a different project.**
`toolbox/mdcode/README.md` (line 101) documents the library path as:
npm install kcmd
import * as kcmd from 'kcmd';
The name on the registry is not this one. `npm view kcmd` returns `1.0.16`,
licence Proprietary, repository `github.com/cengler/kcmd`, an unrelated CLI
that ships its own `kcmd` binary. Its first version was published
2022-02-28, so the name was taken years before this package existed and is
not available to claim. The package here is `0.1.0` and is not on the
registry under that name or any obvious scoped variant.
Following the README therefore installs a stranger's package and, because it
also provides a `kcmd` executable, shadows the CLI documented directly below
it in the same file.
Nothing in-tree catches this: the sibling package depends on it as
`"kcmd": "file:../mdcode"`, and there is no publish workflow, so the
documented path is the only one that touches the registry.
Two ways out, and the choice is yours rather than obvious:
- publish under a scope you control (`@google-cloud/…` or similar) and point
the README at that; or
- drop the `npm install` block until something is published, and document
only the standalone binary and the `file:` dependency, which are what
actually work today.
**2. The enrichment CLI is called `kcenrich` in prose and `kcagent`
everywhere else.**
`toolbox/enrichment/README.md` line 16 says:
> The package provides the `kcenrich` CLI tool.
The example on line 26 runs `kcagent enrich …`, as does the demo on line 162,
and `package.json` declares `bin` entries for `kcagent` and `md-fileset` only.
`kcenrich` is also not on the registry. Assuming `kcagent` is correct, the
sentence is the thing to fix.
*Drafted with Claude Code and reviewed before posting.*
Contributor guide
Research direction
Start with toolbox/mdcode/README.md and toolbox/enrichment/README.md, then compare their commands with the relevant package.json files and the existing file: dependency. Check the documented package and CLI names against the repository metadata. Done means the docs no longer direct readers to an unrelated or unavailable install, and the enrichment CLI name is consistent with the declared and demonstrated command.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, typescript
- Domain
- cli, documentation, tooling
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100