GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

toolbox: the documented `npm install kcmd` resolves to an unrelated package, and the enrichment CLI is named two ways

Open
#289 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.