Skip to content

fix: KEEP-1051 prune stale doc pages, drop a version tag, and rename cmd/protocol - #78

Merged
suisuss merged 3 commits into
mainfrom
fix/KEEP-1051-prune-stale-doc-pages
Jul 28, 2026
Merged

fix: KEEP-1051 prune stale doc pages, drop a version tag, and rename cmd/protocol#78
suisuss merged 3 commits into
mainfrom
fix/KEEP-1051-prune-stale-doc-pages

Conversation

@suisuss

@suisuss suisuss commented Jul 28, 2026

Copy link
Copy Markdown
Contributor

Summary

Follow-up to #76, from reviewing the first sync it produced
(KeeperHub/keeperhub#1843). Making generation run was not sufficient to make
it correct: the reference still contained four pages for commands that no
longer exist, and one page published a version tag.

Three commits, one per issue.

1. Stale pages outlived their commands (81bd0b1)

GenMarkdownTree only writes; it never removes. So a page survives its own
command:

  • kh_protocol.md, kh_protocol_get.md, kh_protocol_list.md - the command
    was renamed to plugin (Use: "plugin"), so cobra generates kh_plugin*.md
    and drops protocol from the index. The old pages stayed.
  • kh_serve.md - serve is Deprecated, so IsAvailableCommand() is false
    and cobra skips it deliberately.

All four kept publishing commands that do not exist. A reader following
kh protocol list gets an error.

docs-check could not catch this, even after #76: an orphan's content never
changes, so it produces no diff. Clearing kh*.md before generating makes the
tree authoritative, so a removal now surfaces as a deletion.

72 -> 68 pages. Only kh*.md is swept; the hand-written guides and the
generator sources share that directory and survive.

2. Version tag in published docs (ca3e3e9)

kh wallet link help text said "v0.1.0 does not launch a browser session
handshake"
, published verbatim to docs.keeperhub.com. Version tags in published
docs go stale silently, and the sentence describes current behaviour rather than
one release's. Fixed at the source and regenerated - editing the page directly
would be overwritten by the next sync.

3. cmd/protocol -> cmd/plugin (f1167cd)

The package declared Use: "plugin"; the directory never followed. That
mismatch is why the orphans went unnoticed
- generated pages were named after
the command, sources after its former name, so neither looked wrong on its own.

No behaviour change and no generated-docs change: the command has been plugin
all along, so regenerating produces an identical tree. That is the evidence it is
a pure refactor.

Verification

The point is not that the orphans were deleted, but that the guard can now catch
them, so I tested that directly:

  • Planted a fake docs/kh_ghostcommand.md, regenerated -> it appears as D, so
    git diff --exit-code docs/ fails. Before this change an orphan produced
    no diff at all.
  • Regenerating after the rename produces an identical tree, confirming commit 3
    changes nothing user-visible.
  • go build, go vet, golangci-lint run ./... (0 issues), full
    go test -race ./... - no failures.

Downstream

KeeperHub/keeperhub#1843 still carries the four orphan pages and the v0.1.0
line, so it should not merge as-is. Once this lands and a release publishes, the
sync regenerates that content correctly - or #1843 can be closed and superseded
by the next automated sync, as #1842 was.

suisuss added 3 commits July 28, 2026 13:15
GenMarkdownTree only writes; it never removes. A page therefore outlives
its own command:

  - kh_protocol.md, kh_protocol_get.md, kh_protocol_list.md - the command
    was renamed to plugin (cmd/protocol/protocol.go declares Use:
    "plugin"), so cobra generates kh_plugin*.md and drops protocol from
    the index, but the old pages stayed
  - kh_serve.md - serve is Deprecated, so IsAvailableCommand() is false
    and cobra skips it by design

All four kept publishing commands that no longer exist. docs-check could
not notice: an orphan's content never changes, so it produces no diff.

Clearing kh*.md before generating makes the tree authoritative, so a
removal now surfaces as a deletion the check can catch. Only kh*.md is
swept - the hand-written guides and the generator sources sit in the same
directory.
The help text stated 'v0.1.0 does not launch a browser session
handshake', which the generator publishes verbatim to
docs.keeperhub.com. Version tags in published docs go stale silently -
the sentence describes current behaviour, not behaviour specific to a
release, so it now says so without pinning a version.

The internal code comment above it keeps its provenance note; only the
published string changes.
…mmand

The package declares Use: "plugin" - it was renamed at some point and
the directory never followed. That mismatch is what let the stale
kh_protocol*.md pages go unnoticed: the generated pages were named after
the command, the source after its former name, so neither looked wrong on
its own.

Renames the directory, protocol.go, the package, and NewProtocolCmd ->
NewPluginCmd, plus the cross-reference in cmd/serve/schemas.go.

No behaviour change and no generated-docs change: the command has been
called plugin all along, so regenerating produces an identical tree.
@suisuss
suisuss merged commit 401eb4c into main Jul 28, 2026
4 checks passed
@suisuss
suisuss deleted the fix/KEEP-1051-prune-stale-doc-pages branch July 28, 2026 03:26
@eskp eskp mentioned this pull request Jul 28, 2026
suisuss added a commit that referenced this pull request Jul 28, 2026
Nothing in the CLI was called enable, so turning a workflow on looked
impossible: pause turns off, go-live publishes a template, update has no
flag. The capability existed as resume - named for the inverse of pause
rather than for the action - so a reader scanning the verb list, or
searching for enable, concluded it was missing and reached for the API or
the web UI.

enable and disable become the primary names. resume, activate and pause
are kept as aliases and stay working indefinitely; scripts, tutorials and
published doc links depend on them, and tests pin each alias to its
command so a later rename cannot quietly drop one. Their help text now
cross-references, so finding one leads to the other.

Runtime output follows the new vocabulary: 'Workflow <id> disabled'
rather than 'paused'. This is a visible change for anyone matching on
that string, and leaving it would have kept the confusion the rename
exists to remove - the command and its own output would disagree.

Regenerating replaces the pause and resume pages with enable and disable,
which is the first real exercise of the pruning added in #78: the old
pages are deleted rather than left behind as orphans.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant