Skip to content

new-plugin scaffolds a provider's source on a kind; which-kind guide (I19.7) - #219

Merged
adssib merged 3 commits into
mainfrom
pl2-scaffold
Nov 21, 2026
Merged

adssib merged 3 commits into
mainfrom
pl2-scaffold

Conversation

@adssib

@adssib adssib commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #218

Closes #178

What this changes

new-plugin scaffolds a provider with sources on the merged kinds (I19.7), and the "which kind?" guide.

  • Flags: --provider <id> --name --category --homepage (a registered provider's come from the registry and must match), --source <id> --kind openapi|changelog|notices|migrationguide|catalog|apisurface --reader … (for a kind with several: changelog markdown|json, notices deprecations|feed, migrationguide sdk|members), --layer, --url and --package (repeatable), --watches, --page, --api (the first name; default <provider>-<source>). In a terminal it asks for what's missing (provider id, then a new provider's name/category/homepage, source id, kind, reader, layer, URLs, packages, watches). One source per run.
  • Per kind it writes the definition with the version wiring the kind needs (an OpenAPI adapter gets a Versions stub next to LatestTag / Fetch; every other kind lists, reads and extracts itself), the RegisterProvider block with every metadata field including Packages, the golden + drop test skeleton over placeholders, the testdata README rows, providers/<name>.md, and the kind's import in plugins/all when it's new. It refuses a taken provider/source id or first name and changes nothing. New template: apisurface (its test builds placeholder wheels in memory).
  • The old flags (--api --provider <Name> --format <format> --source <URL>) still work for one release, mapped to the new kinds.
  • make new-plugin ARGS='…'.
  • docs/which-kind.md: one question per kind, in order; TestWhichKindNamesEveryKind fails if a registered source's kind isn't one of its answers. README, AGENTS.md, CONTRIBUTING.md and docs/writing-a-plugin.md (step 1 = the new flags and prompts) updated; provider pages say "Kind:".

Acceptance criteria

  • The README fits one screen (unchanged length; step 1 is the new command)
  • Every registered source fits one answer of the guide (tested)
  • new-plugin's own test scaffolds one source per kind and reader (9 templates) into a copy of the repo and builds, vets and tests it, and list-plugins lists each with its package

Checks

  • make check passes (tidy, build, gofmt, vet, import allowlist, net/http guard, go test -race, no TODO(new-plugin), leak guard); make contract against patch-it's main fixtures passes (11 files).
  • Goldens: no golden changed

Related PRs

🤖 Generated with Claude Code

--provider/--name/--category/--homepage, --source/--kind/--reader/--layer,
--url and --package (repeatable), asked for in a terminal when missing;
every kind and reader scaffolds (apisurface included, an OpenAPI adapter
gets its Versions stub), plugins/all gets a new kind's import, and the
old --format flags keep working for one release. make new-plugin ARGS=.
docs/which-kind.md asks which kind a source is; a test checks every
registered source's kind is one of its answers.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: adssib <[email protected]>
@claude

claude Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Claude finished @adssib's task in 1m 28s —— View job


⚠️ Merge after fixes. The scaffolder, the guide and the docs are solid and everything passes, but the example command the PR documents fails for a new provider because the name is never asked for (details below).

Rules

Rule Status Evidence
Metadata in the registration (Rule 1) ✅ No source added or changed. The scaffolder's providerBlock writes every field (id, name, category, homepage, source id, layer, page, watches, URLs, Packages). RegisterProvider merges a second block for a registered provider and panics if its metadata differs. No hand-kept list came back.
Provider page ✅ No new provider. The 19 page edits only change "Format plugin:" to "Kind:". Scaffolded pages come from providers/_template.md.
Golden test, quote, drop test ✅ n/a No golden or testdata/ file changed. Every template still writes a golden, a drop file and README rows marked TODO(new-plugin).
Fetch only via env ✅ The new apisurface template's test serves its wheels through env.Get. No net/http added.
Contract fixtures ✅ contract/fixtures/ untouched.
Nothing private (Rule 2) ✅ The diff, the commit message and the PR body name no private hosts or people. The leak guard is clean. The commit is signed off and keeps its co-author trailer.

Bugs

  1. make new-plugin ARGS='--provider acme --source api --kind openapi' fails for a new provider (inline). ask (cmd/new-plugin/resolve.go:77) returns early when the provider id, source id and kind are all given. A provider that isn't registered still needs a name, so Run stops at main.go:246 with --provider "": want the provider's name. That happens even in a terminal, where the PR says the command asks for what's missing. This exact command is the example in the Makefile comment, the AGENTS.md command block and docs/which-kind.md. AGENTS.md's rules section passes --name, so that one is fine. Fix: either drop the early return (prompt and list already skip fields that are set), or also ask when the provider isn't registered and its name is empty. A TestAsksWhatIsMissing case for that would lock it in.

    I found this by reading the code; my run of the command needed approval I didn't have.

Verified

  • go build ./...: OK
  • go vet ./...: no output
  • gofmt -l .: no output
  • go test -race ./...: all packages pass, including cmd/new-plugin (TestScaffoldEveryKind over all 9 templates, 13 s) and plugins/all (TestWhichKindNamesEveryKind)
  • python3 scripts/leak_guard.py --all: "no banned terms (8 hashed terms checked)"
  • git diff --stat over testdata, plugins and contract: only plugins/all/all_test.go changed, so no golden changed
  • Not run: make contract (no patch-it checkout here)

Non-blocking

  • main.go:247: the "no name" error says --provider, but with the new flags the name comes from --name and --provider is the id. Naming the flag based on whether o.Format is set would make the message point at the right one. (I couldn't attach this inline because the line isn't in the diff.)
  • When you add a second source to a registered provider, --page defaults to the new first name, e.g. providers/stripe-python-sdk.md, instead of the provider's existing page. Defaulting to the page its other sources already use (when that page exists) would fit "one page per provider" better.
  • TestWhichKindNamesEveryKind matches | `kind` | as plain text, so a table reformat (padding or alignment) would break it for no real reason. Fine for now.

Comment thread cmd/new-plugin/resolve.go
// when one of the provider id, the source id or the kind is missing (a full
// command line asks nothing).
func ask(o *Options, in *bufio.Reader, out io.Writer) error {
if o.ProviderID != "" && o.SourceID != "" && o.Kind != "" {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

The documented command fails for a new provider. When --provider, --source and --kind are all given, this returns before asking for anything. A new provider's --name is required, though, so make new-plugin ARGS='--provider acme --source api --kind openapi' (the example in the Makefile, the AGENTS.md command block and docs/which-kind.md) stops in Run with:

new-plugin: --provider "": want the provider's name, ...

That happens even in a terminal, where the PR says the command asks for what's missing. One fix: drop the early return, since prompt/list already skip fields that are set. If "a full command line asks nothing" should stay true, change the condition so it also asks when the provider isn't registered and o.Provider == "". Worth adding a TestAsksWhatIsMissing case for an unregistered provider with only these three flags.

Base automatically changed from pl2-apisurface to main November 21, 2026 00:57
@adssib
adssib merged commit 75f9ea9 into main Nov 21, 2026
4 checks passed
@adssib
adssib deleted the pl2-scaffold branch November 21, 2026 00:57
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.

I19.7 · Short README, "which kind fits my source?" guide, new-plugin asks for a kind

1 participant