feat(03-01): add ServeMux groups, JWT verifier, and serve command

Named middleware resolves at boot, HS256 tokens are pinned with required
exp/sub, and both binaries expose a signal-aware serve command.

Co-authored-by: Cursor <cursoragent@cursor.com>

examples/hello/hello_test.go

@@ -3,6 +3,8 @@ package main
 import (
 	"bytes"
 	"crypto/sha256"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"os/exec"
 	"strings"
@@ -13,6 +15,7 @@ import (
 	"git.golem15.com/golem15/summercms/compass"
 	"git.golem15.com/golem15/summercms/pact"
 	"git.golem15.com/golem15/summercms/party"
+	"git.golem15.com/golem15/summercms/surf"
 )
 
 func TestGreeterHelloPrintsLayeredConfig(t *testing.T) {
@@ -104,6 +107,42 @@ func TestBuiltBinaryGreeterHello(t *testing.T) {
 	assertGreeting(t, got, want)
 }
 
+func TestTypedItemRoute(t *testing.T) {
+	cfg, err := compass.Load("config")
+	if err != nil {
+		t.Fatal(err)
+	}
+	application := backpack.New(cfg)
+	plugins, err := party.Activate(application, PluginIDs)
+	if err != nil {
+		t.Fatal(err)
+	}
+	h, err := surf.Assemble(application, plugins)
+	if err != nil {
+		t.Fatal(err)
+	}
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/items/nope", nil))
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("malformed id status = %d", rec.Code)
+	}
+	rec = httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/items/12", nil))
+	if rec.Code != http.StatusOK || rec.Body.String() != `{"id":12}` {
+		t.Fatalf("got %d %s", rec.Code, rec.Body.String())
+	}
+}
+
+func TestHelpListsServe(t *testing.T) {
+	var buf bytes.Buffer
+	if err := run([]string{"--help"}, &buf); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(buf.String(), "serve") {
+		t.Fatalf("help missing serve:\n%s", buf.String())
+	}
+}
+
 func TestMigrateWithoutDSNFailsLoudly(t *testing.T) {
 	var buf bytes.Buffer
 	err := run([]string{"migrate"}, &buf)

examples/hello/main.go

@@ -13,6 +13,7 @@ import (
 	"git.golem15.com/golem15/summercms/lagoon"
 	"git.golem15.com/golem15/summercms/pact"
 	"git.golem15.com/golem15/summercms/party"
+	"git.golem15.com/golem15/summercms/surf"
 )
 
 func main() {
@@ -33,6 +34,7 @@ func run(args []string, out io.Writer) error {
 		return err
 	}
 	commands := lagoon.RuntimeCommands(app, plugins)
+	commands = append(commands, surf.ServeCommand(app, plugins))
 	for _, plugin := range plugins {
 		if hasCommands, ok := plugin.(pact.HasCommands); ok {
 			commands = append(commands, hasCommands.Commands()...)

examples/hello/plugins/greeter/plugin.go

@@ -2,17 +2,24 @@ package greeter
 
 import (
 	"context"
+	"fmt"
+	"net/http"
 
 	"git.golem15.com/golem15/summercms/backpack"
 	"git.golem15.com/golem15/summercms/bonfire"
 	"git.golem15.com/golem15/summercms/festival"
 	"git.golem15.com/golem15/summercms/pact"
 	"git.golem15.com/golem15/summercms/party"
+	"git.golem15.com/golem15/summercms/surf"
 	"git.golem15.com/golem15/summercms/towel"
 )
 
-var _ festival.Collectable = (*HelloEvent)(nil)
-var _ festival.Handleable = (*HelloEvent)(nil)
+var (
+	_ festival.Collectable = (*HelloEvent)(nil)
+	_ festival.Handleable  = (*HelloEvent)(nil)
+	_ pact.HasCommands     = (*Plugin)(nil)
+	_ pact.HasRoutes       = (*Plugin)(nil)
+)
 
 // Plugin is the golem15.greeter plugin. It requires golem15.hello.
 type Plugin struct {
@@ -49,6 +56,19 @@ func (p *Plugin) Boot(app *backpack.App) error {
 	return nil
 }
 
+func (p *Plugin) Routes(r pact.Router) error {
+	r.Get("/items/{id}", func(w http.ResponseWriter, req *http.Request) {
+		id, ok := surf.IntParam(req, "id")
+		if !ok {
+			http.NotFound(w, req)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		fmt.Fprintf(w, `{"id":%d}`, id)
+	})
+	return nil
+}
+
 func (p *Plugin) Commands() []bonfire.Command {
 	return []bonfire.Command{{
 		Name:        "greeter:hello",
@@ -110,8 +130,6 @@ func (e *HelloEvent) IsHandled() bool {
 	return e != nil && e.handled
 }
 
-var _ pact.HasCommands = (*Plugin)(nil)
-
 func init() {
 	party.Register(&Plugin{})
 }