fix(create_project): drop defunct hyperguild new-project from finalize guidance (#46)

The infra#179 partial_failure message and the tool descriptor told callers to
"Finalize locally with `hyperguild new-project`" — but that command does not
exist (the hyperguild CLI only has tier/brain/mode; it was specced, never built).
It pointed users at a dead end.

Extracted the message into a pure infra179FinalizeMessage() and reworded it to
name the actual remaining work — cloning the repo and substituting the leftover
__PROJECT_NAME__ / __MODULE_PATH__ placeholders, or retrying — with no reference
to any scaffolding CLI. Descriptor updated to match. Unit-tested the wording.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

cmd/gitea-mcp/main.go

@@ -20,6 +20,9 @@ import (
 
 func main() {
 	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+	// Route the chassis's package-level slog (auth audit logs, gitea-mcp#9) through
+	// the same structured handler as the rest of the server.
+	slog.SetDefault(logger)
 
 	cfg, err := config.Load()
 	if err != nil {
@@ -56,7 +59,7 @@ func main() {
 	mux := http.NewServeMux()
 	mux.Handle("/mcp", mcp.OriginAllowlist(cfg.OriginAllowlist)(
 		chassisauth.BearerMiddleware(cfg.StaticToken, jwtValidator, "gitea", resourceMetadataURL,
-			auth.CallerMiddleware(mcpSrv),
+			auth.CallerMiddleware(logger, mcpSrv),
 		),
 	))
 	mux.Handle("/healthz", newHealthzHandler(cfg.DexIssuerURL != "", jwtValidator != nil, jwtInitErr))

go.mod

@@ -3,7 +3,7 @@ module git.d-ma.be/mathias/gitea-mcp
 go 1.26.2
 
 require (
-	git.d-ma.be/mathias/mcp-chassis v0.2.0
+	git.d-ma.be/mathias/mcp-chassis v0.3.0
 	github.com/hashicorp/golang-lru/v2 v2.0.7
 	github.com/stretchr/testify v1.11.1
 )

go.sum

@@ -1,5 +1,5 @@
-git.d-ma.be/mathias/mcp-chassis v0.2.0 h1:6fLmb7xqRa2nNVWsHaUbbfbArgDXJw/gDhb09clBIjo=
+git.d-ma.be/mathias/mcp-chassis v0.3.0 h1:lV/vDsjrDeZojT7lhcwolM1lMZpsnEKEvf4kEHrxIa0=
-git.d-ma.be/mathias/mcp-chassis v0.2.0/go.mod h1:Ks7EK2UnGAN0H3rJjKUxUagX8/ZBdtLrOlcUbv0RwH8=
+git.d-ma.be/mathias/mcp-chassis v0.3.0/go.mod h1:Ks7EK2UnGAN0H3rJjKUxUagX8/ZBdtLrOlcUbv0RwH8=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=

internal/auth/caller.go

@@ -2,17 +2,40 @@ package auth
 
 import (
 	"context"
+	"log/slog"
 	"net/http"
 )
 
 type ctxKey struct{}
 
-func CallerMiddleware(next http.Handler) http.Handler {
+// CallerMiddleware extracts the authenticated username from the reverse-proxy
+// identity headers and stashes it in the request context for Caller().
+//
+// Header precedence: X-Auth-Request-User takes priority over X-Forwarded-User.
+// X-Auth-Request-User is the header oauth2-proxy sets from the *verified* OIDC
+// identity, so it is authoritative. X-Forwarded-User is a weaker, proxy-set
+// convention some setups populate instead; it is used only as a fallback when
+// X-Auth-Request-User is absent. If a proxy sets BOTH and they disagree, the
+// verified X-Auth-Request-User still wins and we log a warning so the
+// misconfiguration is visible rather than silently resolved (#10).
+//
+// logger may be nil, in which case the conflict warning is skipped.
+func CallerMiddleware(logger *slog.Logger, next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		user := r.Header.Get("X-Auth-Request-User")
+		authUser := r.Header.Get("X-Auth-Request-User")
+		fwdUser := r.Header.Get("X-Forwarded-User")
+
+		user := authUser
 		if user == "" {
-			user = r.Header.Get("X-Forwarded-User")
+			user = fwdUser
 		}
+
+		if logger != nil && authUser != "" && fwdUser != "" && authUser != fwdUser {
+			logger.Warn("conflicting caller identity headers; using X-Auth-Request-User",
+				"x_auth_request_user", authUser,
+				"x_forwarded_user", fwdUser)
+		}
+
 		ctx := context.WithValue(r.Context(), ctxKey{}, user)
 		next.ServeHTTP(w, r.WithContext(ctx))
 	})

internal/auth/caller_test.go

@@ -1,7 +1,9 @@
 package auth_test
 
 import (
+	"bytes"
 	"context"
+	"log/slog"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -10,17 +12,69 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
-func TestCallerFromContext(t *testing.T) {
+func discardLogger() *slog.Logger {
-	called := false
+	return slog.New(slog.NewTextHandler(bytes.NewBuffer(nil), nil))
-	h := auth.CallerMiddleware(http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+}
-		called = true
+
-		assert.Equal(t, "mathiasbq", auth.Caller(r.Context()))
+// Header precedence: X-Auth-Request-User (verified OIDC identity) wins over
+// X-Forwarded-User, and X-Forwarded-User is only a fallback when the former is
+// absent.
+func TestCallerHeaderPrecedence(t *testing.T) {
+	tests := []struct {
+		name       string
+		authReq    string
+		forwarded  string
+		wantCaller string
+	}{
+		{"auth-request only", "mathiasbq", "", "mathiasbq"},
+		{"forwarded fallback", "", "fwduser", "fwduser"},
+		{"both present, same", "same", "same", "same"},
+		{"both present, differ → auth-request wins", "authuser", "fwduser", "authuser"},
+		{"neither", "", "", ""},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			var got string
+			h := auth.CallerMiddleware(discardLogger(), http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+				got = auth.Caller(r.Context())
 			}))
 			req := httptest.NewRequest(http.MethodPost, "/", nil)
-	req.Header.Set("X-Auth-Request-User", "mathiasbq")
+			if tc.authReq != "" {
-	rr := httptest.NewRecorder()
+				req.Header.Set("X-Auth-Request-User", tc.authReq)
-	h.ServeHTTP(rr, req)
+			}
-	assert.True(t, called)
+			if tc.forwarded != "" {
+				req.Header.Set("X-Forwarded-User", tc.forwarded)
+			}
+			h.ServeHTTP(httptest.NewRecorder(), req)
+			assert.Equal(t, tc.wantCaller, got)
+		})
+	}
+}
+
+// When both headers are present and disagree, a warning is logged so the proxy
+// misconfiguration is visible rather than silent.
+func TestCallerConflictingHeadersLogsWarning(t *testing.T) {
+	var buf bytes.Buffer
+	logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{Level: slog.LevelWarn}))
+
+	h := auth.CallerMiddleware(logger, http.HandlerFunc(func(_ http.ResponseWriter, _ *http.Request) {}))
+	req := httptest.NewRequest(http.MethodPost, "/", nil)
+	req.Header.Set("X-Auth-Request-User", "authuser")
+	req.Header.Set("X-Forwarded-User", "fwduser")
+	h.ServeHTTP(httptest.NewRecorder(), req)
+
+	logged := buf.String()
+	assert.Contains(t, logged, "conflicting")
+	assert.Contains(t, logged, "authuser")
+	assert.Contains(t, logged, "fwduser")
+
+	// No warning when they agree.
+	buf.Reset()
+	req2 := httptest.NewRequest(http.MethodPost, "/", nil)
+	req2.Header.Set("X-Auth-Request-User", "same")
+	req2.Header.Set("X-Forwarded-User", "same")
+	h.ServeHTTP(httptest.NewRecorder(), req2)
+	assert.Empty(t, buf.String(), "no warning expected when headers agree")
 }
 
 func TestCallerEmptyWhenHeaderMissing(t *testing.T) {

internal/tools/create_project_from_template.go

@@ -48,7 +48,7 @@ func NewCreateProjectFromTemplate(c *gitea.Client, a *allowlist.Allowlist, tmplO
 func (t *CreateProjectFromTemplate) Descriptor() registry.ToolDescriptor {
 	return registry.ToolDescriptor{
 		Name:        "create_project_from_template",
-		Description: "Create a new project repo from a template. Best-effort substitution of placeholders (__PROJECT_NAME__, __MODULE_PATH__) in every file's content AND path (e.g. renaming cmd/__PROJECT_NAME__/): it completes only if the generated branch is promptly writable. If gitea's async generate is slow (infra#179) the repo is still created and partial_failure explains how to finalize locally (`hyperguild new-project`). Check files_substituted and partial_failure. Defaults to the server-configured template; pass template_name to override (e.g. template-go-agent). Pass dispatch_allow=true to also inject a .dispatch-allow file so the project is immediately dispatch-eligible (dispatch#3).",
+		Description: "Create a new project repo from a template. Best-effort substitution of placeholders (__PROJECT_NAME__, __MODULE_PATH__) in every file's content AND path (e.g. renaming cmd/__PROJECT_NAME__/): it completes only if the generated branch is promptly writable. If gitea's async generate is slow (infra#179) the repo is still created and partial_failure explains how to finish substituting the placeholders manually. Check files_substituted and partial_failure. Defaults to the server-configured template; pass template_name to override (e.g. template-go-agent). Pass dispatch_allow=true to also inject a .dispatch-allow file so the project is immediately dispatch-eligible (dispatch#3).",
 		InputSchema: json.RawMessage(`{
 			"type":"object",
 			"properties":{
@@ -209,11 +209,7 @@ func (t *CreateProjectFromTemplate) Call(ctx context.Context, raw json.RawMessag
 	// is best-effort).
 	if strings.Contains(result.PartialFailure, "branch does not exist") ||
 		strings.Contains(result.PartialFailure, "not found") {
-		result.PartialFailure = fmt.Sprintf(
+		result.PartialFailure = infra179FinalizeMessage(
-			"repo created, but its branch (%s) was not writable within %ds — gitea's "+
-				"template-generate is slow-async on this instance (infra#179), so substitution "+
-				"is incomplete (%d file(s) done). Finalize locally with `hyperguild new-project` "+
-				"(clone + substitute, no API race). Underlying: %s",
 			branch, substitutionBudget, len(result.FilesSubstituted), result.PartialFailure)
 	}
 
@@ -227,6 +223,21 @@ func (t *CreateProjectFromTemplate) Call(ctx context.Context, raw json.RawMessag
 	return textOK(result)
 }
 
+// infra179FinalizeMessage explains the best-effort outcome when gitea's slow
+// async template-generate (infra#179) leaves the branch unwritable within the
+// budget. It names the concrete remaining work — substituting the two
+// placeholders — rather than pointing at a specific tool, so the guidance stays
+// correct regardless of scaffolding-CLI state (gitea-mcp#46).
+func infra179FinalizeMessage(branch string, budget, done int, underlying string) string {
+	return fmt.Sprintf(
+		"repo created, but its branch (%s) was not writable within %ds — gitea's "+
+			"template-generate is slow-async on this instance (infra#179), so substitution "+
+			"is incomplete (%d file(s) done). Finish it by cloning the repo and replacing the "+
+			"remaining __PROJECT_NAME__ / __MODULE_PATH__ placeholders (in file contents and "+
+			"paths), then pushing; or retry create once the branch settles. Underlying: %s",
+		branch, budget, done, underlying)
+}
+
 // substitutionBudget bounds how long we retry the first write while the freshly
 // generated branch becomes writable. gitea's /generate returns (and serves reads)
 // before the branch ref is committed, so writes 404 "branch does not exist" for a

internal/tools/create_project_internal_test.go

@@ -0,0 +1,22 @@
+package tools
+
+import (
+	"strings"
+	"testing"
+)
+
+// #46: the infra#179 finalize guidance must not point at a non-existent command
+// (`hyperguild new-project` was never built). It should name the real remaining
+// work — substituting the placeholders — so the caller isn't sent to a dead end.
+func TestInfra179FinalizeMessage(t *testing.T) {
+	msg := infra179FinalizeMessage("main", 5, 2, "branch does not exist")
+
+	for _, want := range []string{"infra#179", "__PROJECT_NAME__", "__MODULE_PATH__", "branch does not exist"} {
+		if !strings.Contains(msg, want) {
+			t.Errorf("message missing %q\ngot: %s", want, msg)
+		}
+	}
+	if strings.Contains(msg, "hyperguild new-project") {
+		t.Errorf("message must not reference the defunct `hyperguild new-project` command\ngot: %s", msg)
+	}
+}

internal/tools/pr_create_test.go

@@ -30,7 +30,7 @@ const prFixture = `{
 
 func callerContext(user string) context.Context {
 	var capturedCtx context.Context
-	h := auth.CallerMiddleware(http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
+	h := auth.CallerMiddleware(nil, http.HandlerFunc(func(_ http.ResponseWriter, r *http.Request) {
 		capturedCtx = r.Context()
 	}))
 	req := httptest.NewRequest("POST", "/", nil)