Skip to content

feat: Build a deprecation notice that names the replacement - #374

Merged
0xmc merged 2 commits into
mainfrom
feat/368-deprecation-notice
Nov 17, 2026
Merged

0xmc merged 2 commits into
mainfrom
feat/368-deprecation-notice

Conversation

@0xmc

@0xmc 0xmc commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Summary

Each plugin command needs to tell people the same thing about a deprecated plugin: what replaces it and the exact commands to switch.

This adds the shared notice, which recognizes a replacement catalog the user already added under any name and says so when an allow-list disables it.

Catalog text can't inject terminal control sequences or a shell command into the printed commands. No command prints the notice yet, and the next PRs in the #355 stack wire it in.

Test plan

  • A replacement catalog the user added under another name gets only the install command
  • A source containing a shell command, or a disabled catalog, gets no command lines
  • Build, vet, and the plugin command tests pass

Stacked on #373. Fixes #368

🤖 Generated with Claude Code

Base automatically changed from feat/367-plugin-deprecation-format to main November 17, 2026 17:42
Every plugin command needs to tell people the same thing about a
deprecated plugin: what replaces it and the exact commands to
switch. This adds the one helper they will share.

The notice finds the replacement's catalog by source among the
catalogs the user already added, under whatever name they chose,
preferring an enabled catalog when the same source is added twice,
and then prints only the install command. Otherwise it suggests a
catalog name from the GitHub owner, falling back to a <name>
placeholder when that name is invalid or taken. When an allow-list
disables the replacement's catalog it says so instead of printing
commands that would fail.

Catalog authors control the text, so control and format characters
are stripped, and command lines are printed only when the
replacement name and source pass a strict character check (no
leading "-") and the source resolves. A source such as
"x; curl ... | sh" gets a "not valid" line instead of a copy-paste
command.

No command prints the notice yet; follow-up changes wire it in.

Resolves: #368

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@0xmc
0xmc force-pushed the feat/368-deprecation-notice branch from d68dbaa to 571d71b Compare November 17, 2026 17:47
@0xmc
0xmc marked this pull request as ready for review November 17, 2026 18:41
@0xmc
0xmc requested a review from a team as a code owner November 17, 2026 18:41
@0xmc
0xmc enabled auto-merge November 17, 2026 18:42
@0xmc

0xmc commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

Second-pass review on head 571d71b agreed to merge.

pr-rereviewer: VERDICT merge. The leading-dash test (TestDeprecationNotice_leadingDashSource) is confirmed fixed and no longer inert: with a tamper that allowed a leading "-" in reReplacementSource it failed with "datumctl plugin index add -x" in the output, and it passes untampered. The preference for an enabled catalog in findCatalogBySource is confirmed fixed (tamper-tested in the prior pass). The squashed commit is signed, its body covers both fixes, and the trailer matches the configured attribution. It ran: git log --show-signature; git diff d68dbaa 571d71b --stat; git log 4629ef7..571d71b; go test -run TestDeprecationNotice; a scratch worktree tamper of deprecation.go:17 with the focused test (worktree removed).

pr-conventions-reviewer: VERDICT merge. Nits only (commit subject is 59 characters against a 50 target, under the 72 hard limit; possible comment trimming), not applied. It ran: git log and diff over base..head; gh pr view; gh pr list for overlap (none beyond the stack); go build, go vet and go test on ./internal/cmd/plugin/.

History: both reviewers returned merge on the first pass. The fix phase applied an enabled-catalog preference and a leading-dash guard. The first re-review held because the leading-dash test was inert. The test was fixed and, with approval, the branch was squashed to one commit, which is the head reviewed here.

CI: ci / Build and test and license/cla both passed on 571d71b.

Auto-merge is enabled with the merge-commit method, the only one the ruleset allows. The ruleset requires one approving review, code owner review and approval of the last push, so the PR waits for a human approval.

PRs #375, #376 and #378 are stacked on this PR.

@ecv ecv left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve.

Sanitization and quoting hold against hostile input: control characters, bidi and other format characters are stripped, and every character that reaches a printed command is on an allow-list. Nothing calls it yet, and the stacked PRs (#375, #378) call writeDeprecationNotice(w, reg, name, d) with the signature built here.

  • Ran hostile catalog text through writeDeprecationNotice: ESC, CSI, OSC 8 with BEL, U+202E, U+2066, U+0085 and U+200B all vanish from the output, and a \n in the message or plugin name cannot forge a line. Sources such as acme/tools$(id), backticks, ;, |, ', \n, a Cyrillic lookalike, ~root/x and file:// all fall to the "not valid" line with no command printed.
  • Tamper tests: removing the control-character strip fails TestDeprecationNotice_sanitizesMessage and TestDeprecationNotice_stripsFormatChars; removing the Cf strip fails stripsFormatChars; removing the source allow-list fails leadingDashSource. The guards are covered.
  • Stack fit: #375 and #378 call it with p.Spec.Deprecated and the loaded registry, writing to cmd.ErrOrStderr(), so the shape fits.

Follow-ups:

  • U+2028 and U+2029 are not stripped (they are Zl and Zp, not control or Cf), and pass through in the message and the disabled reason. Most terminals do not break a line on them, but strip them with the other characters.
  • An absolute local path as the replacement source (/etc/passwd) passes the checks and prints datumctl plugin index add <name> /etc/passwd. A remote catalog can suggest a path on the user's own disk; reject local-path sources from catalog text.
  • c.Name of a registered catalog is printed with %s in the install line unsanitized (the disabled branch uses %q). It comes from the user's own registry, not catalog text, so low risk; running it through ValidateCatalogName would close it.

@0xmc
0xmc merged commit ecbbabf into main Nov 17, 2026
2 checks passed
@0xmc
0xmc deleted the feat/368-deprecation-notice branch November 17, 2026 19:25
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.

Deprecated plugins need a notice naming the replacement

2 participants