go-demo-surface-route-drift

Answer

Root cause. The project has two independent route-registration sites:

1. internal/api/designs.go — defines the contract handlers (Materials, Costs, Design) for the /projects/{id}/... family.
2. internal/cli/serve.go — the full server, which registers them (this is where the gap-fix task added them).
3. cmd/demo/main.go — the demo surface, which keeps its own curated route table. It was not updated when the full server gained the three routes, so the demo binary 404s /projects/{id}/materials, /projects/{id}/costs, and /projects/{id}/design.

Fix part 1 — register the missing routes in cmd/demo/main.go (minimal, restores parity):

// cmd/demo/main.go
package main

import (
    "log"
    "net/http"

    "example.com/project/internal/api"
)

type route struct {
    method  string
    pattern string
    handler http.HandlerFunc
}

// Demo surface route table — MUST mirror internal/cli/serve.go.
var routes = []route{
    {http.MethodGet, "/projects", api.ListProjects},
    {http.MethodGet, "/projects/{id}", api.GetProject},
    // Gap-fix added these to the full server; demo table drifted. Re-added:
    {http.MethodGet, "/projects/{id}/materials", api.GetProjectMaterials},
    {http.MethodGet, "/projects/{id}/costs", api.GetProjectCosts},
    {http.MethodGet, "/projects/{id}/design", api.GetProjectDesign},
}

func main() {
    mux := http.NewServeMux()
    for _, r := range routes {
        mux.HandleFunc(r.method+" "+r.pattern, r.handler)
    }
    log.Fatal(http.ListenAndServe(":8080", mux))
}

The three added rows must exactly mirror the full server's registrations in internal/cli/serve.go:

// internal/cli/serve.go (full server — already correct)
mux.HandleFunc("GET /projects/{id}/materials", api.GetProjectMaterials)
mux.HandleFunc("GET /projects/{id}/costs", api.GetProjectCosts)
mux.HandleFunc("GET /projects/{id}/design", api.GetProjectDesign)

Fix part 2 — kill the drift at the source (durable, prevents recurrence). Export a single registration function from internal/api and have both surfaces call it, so there is one source of truth:

// internal/api/designs.go
// RegisterDesignRoutes attaches the /projects/{id}/... contract routes to mux.
// Both the full server and the demo surface MUST call this — never register
// these routes ad hoc in a server main.
func RegisterDesignRoutes(mux *http.ServeMux) {
    mux.HandleFunc("GET /projects/{id}/materials", GetProjectMaterials)
    mux.HandleFunc("GET /projects/{id}/costs", GetProjectCosts)
    mux.HandleFunc("GET /projects/{id}/design", GetProjectDesign)
}

// cmd/demo/main.go — demo now derives its table from the shared registrar
func main() {
    mux := http.NewServeMux()
    api.RegisterDesignRoutes(mux)
    // ... any demo-only routes ...
    log.Fatal(http.ListenAndServe(":8080", mux))
}

Fix part 3 — guard test so the battery cannot regress silently. Assert that every contract route registered by the full server is also reachable via the demo server's mux:

// cmd/demo/main_test.go
func TestDemoRoutesMatchFullServer(t *testing.T) {
    demo := newDemoMux()          // routes from Fix part 1 / part 2
    full := newFullServerMux()    // internal/cli/serve.go registration

    contractRoutes := []string{
        "GET /projects/{id}/materials",
        "GET /projects/{id}/costs",
        "GET /projects/{id}/design",
    }
    for _, pat := range contractRoutes {
        if _, err := demo.Handler(nil, pat); err != nil { // or pattern-match against table
            t.Errorf("demo server missing contract route %q registered by full server", pat)
        }
    }
    _ = full
}

Pattern to adopt: whenever a gap-fix task touches internal/api or internal/cli/serve.go, grep cmd/demo/main.go's route table in the same change and mirror any additions.