golem15/summercms
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(build): summer plugin:install for registry plugins as Go modules

Browse Source 
- kiosk.Client reads the registry API v1 over fetchguard (trusted mode,
  4 MiB, 10 s, no redirects); kiosk.RegistryURL reads plugins.registry_url
  (default https://summercms.io, empty disables)
- build.PlanInstall/ApplyInstall pick the newest release the effective
  framework satisfies (or a pin), validate registry strings, go get it and
  append it to summer.yaml
- summer.yaml edits (plugin:add and plugin:install) keep comments and
  blank lines
- TestInstallSmoke/module installs from a file:// GOPROXY and builds
This commit is contained in:
Jakub Zych
2026-10-29 18:22:01 +01:00
parent e7eda88ddd
commit 9b23e877a6
10 changed files with 1323 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
modules/kiosk/README.md
View File

@@ -21,6 +21,7 @@ WinterCMS keeps this data in a plugin's `Plugin.php` `pluginDetails()` and in `c
- Name and description overrides (`--name`, `--description`) stored in an `overrides:` block that regeneration keeps.
- The registry API v1 contract in Go: `kiosk.RegistryAPIPath` and the wire types (`kiosk.ListResponse`, `kiosk.DetailResponse`, `kiosk.VersionsResponse`, `kiosk.ErrorResponse`, `kiosk.IngestRequest`, `kiosk.IngestResponse`). The registry server encodes with them and the summer tool and the admin decode with them, so the JSON shape exists once.
- Strict version rules: `kiosk.ValidVersion` (only `vX.Y.Z`), `kiosk.CompareVersions`, `kiosk.BaseVersion` for `git describe` output, `kiosk.Satisfies` for Go-style minimums and `kiosk.NewestCompatible` to pick the release an application can install.
- A registry client, `kiosk.Client`, for the summer tool and the admin: `kiosk.NewClient` builds it over a `fetchguard` client in trusted mode with a 4 MiB body cap, a 10 second timeout and no redirects, and `kiosk.RegistryURL` reads the registry origin from the `plugins.registry_url` config key (default `kiosk.DefaultRegistryURL`; an empty value disables registry calls).
- `kiosk.Check` regenerates in memory and returns a `kiosk.StaleError` when the committed file is missing or differs, which `summer plugin:manifest --check` turns into exit status 1, and `kiosk.CheckT` turns into a failing test in the plugin's own `go test`.
## Usage
@@ -58,6 +59,22 @@ if !ok {
fmt.Println("go get", v.Module+"@"+v.Version)
```
Asking the configured registry for a plugin's releases:
```go
client, err := kiosk.NewClient(kiosk.RegistryURL(app.Config), app.Config)
if errors.Is(err, kiosk.ErrRegistryDisabled) {
return nil // plugins.registry_url is empty: no registry calls
}
if err != nil {
return err
}
versions, err := client.Versions(ctx, "acme.blog")
if errors.Is(err, kiosk.ErrNotFound) {
return fmt.Errorf("acme.blog is not listed")
}
```
A plugin repository keeps its manifest current with one test:
```go
@@ -111,21 +128,38 @@ func TestPluginManifest(t *testing.T) {
| `kiosk.BaseVersion` | The `vX.Y.Z` tag a `git describe --tags` string starts from (`v0.3.1` for `v0.3.1-4-gabc1234`), or `""`. |
| `kiosk.Satisfies` | Whether a release meets a minimum; an empty minimum is always met, and a pseudo-version minimum is met by its base release and later. |
| `kiosk.NewestCompatible` | The newest release whose framework minimum a framework version satisfies. |
| `kiosk.DefaultRegistryURL` | `https://summercms.io`, the registry used when `plugins.registry_url` is not set. |
| `kiosk.RegistryURL` | The registry origin from a `compass.Config`: the `plugins.registry_url` value without a trailing slash, `kiosk.DefaultRegistryURL` when the key is absent, `""` (disabled) when it is set empty. |
| `kiosk.ErrRegistryDisabled` | Returned by `kiosk.NewClient` for an empty base URL. |
| `kiosk.ErrNotFound` | Wrapped by a `kiosk.Client` error when the registry answers 404; the message names the ID and the registry origin. |
| `kiosk.Client` | Calls the registry API v1 of one origin through `fetchguard` (trusted mode, 4 MiB cap, 10 s timeout, no redirects). |
| `kiosk.NewClient` | Builds a client for an `http` or `https` origin without user info, query or fragment; the config supplies fetchguard defaults and may be nil. |
| `kiosk.Client.BaseURL` | The origin the client calls. |
| `kiosk.Client.List` | `GET /plugins?q=&category=`, decoded as a `kiosk.ListResponse`. |
| `kiosk.Client.Plugin` | `GET /plugins/{id}`: one `kiosk.RegistryPluginDetail`. |
| `kiosk.Client.Versions` | `GET /plugins/{id}/versions`: the plugin's `kiosk.RegistryVersion` list, newest first. A non-2xx answer other than 404 is an error carrying the registry's error code; a redirect is an error asking for the final origin. |
| `kiosk.Identity` | The plugin ID and the required plugin IDs. |
| `kiosk.ReadIdentity` | Reads what `ID()` and `Requires()` return from the sources of a directory, resolving constants across packages and modules without running code. Any other expression is an error naming the method. |
| `kiosk.StaleError` | `Path`, `Missing`, and the generated (`Want`) and committed (`Got`) bytes; its message names the first differing line. |
## Configuration
| Key | Default | Meaning |
|-----|---------|---------|
| `plugins.registry_url` | `https://summercms.io` | Registry origin for `summer plugin:install` and the admin's Plugins screen (file `config/plugins.yaml`, env `SUMMER_PLUGINS__REGISTRY_URL`). It must be the final origin, because redirects are not followed. An empty value disables registry calls. |
## CLI commands
| Command | Purpose |
|---------|---------|
| `summer plugin:manifest [dir]` | Writes `plugin.yaml` for the plugin in `dir` (default: the current directory). `--pretend` prints it instead, `--check` fails when the committed file is missing or stale, `--name` and `--description` set or (with an empty value) clear the overrides. |
| `summer plugin:install <id\|git-url>` | Installs a plugin; reads its releases through `kiosk.Client` and picks one with `kiosk.NewestCompatible`. See [Installing plugins](../../docs/plugins/marketplace.md#installing-plugins). |
## Dependencies
- SummerCMS modules: none.
- SummerCMS modules: `compass` (the `plugins.registry_url` setting), `fetchguard` (registry HTTP calls).
- Third-party: `github.com/goccy/go-yaml` (manifest YAML), `github.com/yuin/goldmark` (README headings and paragraphs).
- Standard library: `bytes`, `context`, `encoding/json`, `errors`, `fmt`, `go/ast`, `go/parser`, `go/token`, `go/types` (expression printing only), `os`, `os/exec`, `path/filepath`, `regexp`, `slices`, `sort`, `strconv`, `strings`, `time`.
- Standard library: `bytes`, `context`, `encoding/json`, `errors`, `fmt`, `go/ast`, `go/parser`, `go/token`, `go/types` (expression printing only), `net/http`, `net/url`, `os`, `os/exec`, `path/filepath`, `regexp`, `slices`, `sort`, `strconv`, `strings`, `time`.
- Tools: the `go` command (`go mod edit -json`, `go list -m -json`, and `go mod download -json` for a required module not in the module cache), run without a shell and with workspaces off.
## Testing
@@ -135,3 +169,5 @@ go test ./modules/kiosk/...
```
`TestManifestSmoke` copies the fixture plugins in `testdata/` to a temporary directory and generates, checks and edits their manifests: a literal-ID plugin, a plugin whose identity is spread over constants of three packages and two modules, a nested plugin, the error cases, overrides, `kiosk.CheckT` and `kiosk.Validate`, the registry JSON (golden bytes, unknown fields ignored) and the version rules. Every fixture module replaces the framework with the stub in `testdata/framework`, so the tests run the local `go` command but need no network and no database.
The registry client (`kiosk.Client`) is exercised by `TestInstallSmoke` in `internal/build`, against an `httptest` registry that serves these wire types.