Dashboard contract slice a

.gitignore

@@ -122,6 +122,10 @@ METRICS_DEADLOCK_FIX.md
 !README.md
 **/*.md
 !**/README.md
+!extensions/dashboard/contract/*.md
+!extensions/dashboard/contract/shell/*.md
+!extensions/dashboard/contract/shell/test/
+!extensions/dashboard/contract/shell/test/**
 /**/*.disabled
 extensions/dashboard/forgeui
 *.blob

cmd/dashboard-contract-probe/main.go

@@ -0,0 +1,41 @@
+// main.go
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+
+	"github.com/xraph/forge/extensions/dashboard/contract"
+)
+
+func main() {
+	base := flag.String("base", "http://localhost:8080", "dashboard base URL (no trailing slash)")
+	kind := flag.String("kind", "query", "graph | query | command")
+	contributor := flag.String("contributor", "", "contributor name")
+	intent := flag.String("intent", "", "intent name")
+	payload := flag.String("payload", "{}", "JSON payload")
+	csrf := flag.String("csrf", "", "CSRF token (required for command)")
+	idem := flag.String("idem", "", "idempotency key (required for command)")
+	flag.Parse()
+
+	req := contract.Request{
+		Envelope: "v1", Kind: contract.Kind(*kind),
+		Contributor: *contributor, Intent: *intent,
+		Payload: json.RawMessage(*payload),
+		CSRF:    *csrf, IdempotencyKey: *idem,
+	}
+	body, _ := json.Marshal(req)
+	resp, err := http.Post(*base+"/api/dashboard/v1", "application/json", bytes.NewReader(body))
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "request:", err)
+		os.Exit(1)
+	}
+	defer resp.Body.Close()
+	out, _ := io.ReadAll(resp.Body)
+	fmt.Printf("HTTP %d\n%s\n", resp.StatusCode, out)
+}

cmd/forge/plugins/dev.go

@@ -9,6 +9,7 @@ import (
 	"os/exec"
 	"os/signal"
 	"path/filepath"
+	"runtime"
 	"strconv"
 	"strings"
 	"sync"
@@ -641,6 +642,35 @@ func newAppWatcher(cfg *config.ForgeConfig, app *AppInfo) (*appWatcher, error) {
 // have been extracted to dev_shared.go as package-level functions shared with
 // dockerAppWatcher.
 
+// buildApp compiles the user's main package into a stable per-app path inside
+// the project's .forge/dev directory. We rebuild in place each time so the
+// path stays predictable (helpful for debuggers and codesigning) and old
+// artifacts don't accumulate in the OS temp dir.
+func (aw *appWatcher) buildApp() (string, error) {
+	buildDir := filepath.Join(aw.config.RootDir, ".forge", "dev")
+	if err := os.MkdirAll(buildDir, 0o755); err != nil {
+		return "", fmt.Errorf("create build dir: %w", err)
+	}
+
+	binName := aw.app.Name
+	if binName == "" {
+		binName = "app"
+	}
+	if runtime.GOOS == "windows" {
+		binName += ".exe"
+	}
+	binPath := filepath.Join(buildDir, binName)
+
+	cmd := exec.Command("go", "build", "-tags", "forge_debug", "-o", binPath, aw.mainFile)
+	cmd.Dir = aw.config.RootDir
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	if err := cmd.Run(); err != nil {
+		return "", fmt.Errorf("go build: %w", err)
+	}
+	return binPath, nil
+}
+
 // Start starts the application process.
 func (aw *appWatcher) Start(ctx cli.CommandContext) error {
 	aw.mu.Lock()
@@ -671,9 +701,19 @@ func (aw *appWatcher) Start(ctx cli.CommandContext) error {
 
 	ctx.Success(fmt.Sprintf("Starting %s...", aw.app.Name))
 
-	// Create new command — compile with forge_debug tag so the in-process
-	// debug server is included; disabled automatically in release builds.
-	cmd := exec.Command("go", "run", "-tags", "forge_debug", aw.mainFile)
+	// Build the binary first, then exec it directly. We deliberately avoid
+	// `go run` here: it spawns the compiled binary as a grandchild, and on
+	// abrupt shutdown (kill -9 of forge dev, parent shell exit) those
+	// grandchildren get reparented to PID 1 and survive with their dispatch
+	// loops still hammering the database. Building once and exec'ing the
+	// binary directly means there's exactly one process to track and
+	// killProcessGroup reliably reaches it.
+	binPath, err := aw.buildApp()
+	if err != nil {
+		return fmt.Errorf("build failed: %w", err)
+	}
+
+	cmd := exec.Command(binPath)
 	cmd.Dir = aw.config.RootDir
 	cmd.Stdout = os.Stdout
 	cmd.Stderr = os.Stderr
@@ -1000,11 +1040,15 @@ func (p *DevPlugin) startContributorDevServers(ctx cli.CommandContext) []*contri
 			devCmd = adapter.DefaultDevCmd()
 		}
 
-		// Start the dev server
+		// Start the dev server. Put the shell in its own process group so
+		// killProcessGroup can take down the whole tree (npm/node/vite/...)
+		// instead of just the sh wrapper, which would otherwise leave the
+		// real dev server orphaned on rebuild.
 		cmd := exec.Command("sh", "-c", devCmd)
 		cmd.Dir = uiDir
 		cmd.Stdout = os.Stdout
 		cmd.Stderr = os.Stderr
+		setupProcessGroup(cmd)
 
 		if err := cmd.Start(); err != nil {
 			ctx.Warning(fmt.Sprintf("Failed to start contributor dev server %s: %v", cfg.Name, err))
@@ -1024,9 +1068,13 @@ func (p *DevPlugin) startContributorDevServers(ctx cli.CommandContext) []*contri
 // stopContributorDevServers stops all running contributor dev server processes.
 func stopContributorDevServers(processes []*contributorDevProcess) {
 	for _, proc := range processes {
-		if proc.Cmd != nil && proc.Cmd.Process != nil {
-			proc.Cmd.Process.Kill()
-			proc.Cmd.Process.Wait()
+		if proc.Cmd == nil || proc.Cmd.Process == nil {
+			continue
 		}
+		// killProcessGroup tears down the whole sh→npm→node tree. A bare
+		// Process.Kill would only stop the sh wrapper, leaving npm/node
+		// running and holding the dev port.
+		killProcessGroup(proc.Cmd)
+		_, _ = proc.Cmd.Process.Wait()
 	}
 }

extensions/dashboard/auth/context.go

@@ -1,6 +1,9 @@
 package dashauth
 
-import "context"
+import (
+	"context"
+	"net/http"
+)
 
 type contextKey string
 
@@ -47,3 +50,37 @@ func HasTenantInContext(ctx context.Context) bool {
 
 	return t.HasTenant()
 }
+
+const (
+	respWriterContextKey contextKey = "forge:dashboard:resp"
+	requestContextKey    contextKey = "forge:dashboard:req"
+)
+
+// WithHTTP stashes the live ResponseWriter and Request on ctx so contract
+// command handlers that legitimately need to touch HTTP — e.g. the auth
+// extension's auth.login handler that issues a Set-Cookie — can reach them.
+// The contract transport calls this before dispatching commands.
+//
+// Most contract handlers are pure data and should NOT pull these out;
+// reaching for the response writer is an escape hatch for the small set of
+// concerns where the cookie/header IS the contract (auth, downloads).
+func WithHTTP(ctx context.Context, w http.ResponseWriter, r *http.Request) context.Context {
+	ctx = context.WithValue(ctx, respWriterContextKey, w)
+	ctx = context.WithValue(ctx, requestContextKey, r)
+	return ctx
+}
+
+// ResponseWriterFromContext returns the ResponseWriter previously stashed by
+// WithHTTP, or nil when called outside an HTTP-served dispatch (background
+// jobs, tests).
+func ResponseWriterFromContext(ctx context.Context) http.ResponseWriter {
+	w, _ := ctx.Value(respWriterContextKey).(http.ResponseWriter)
+	return w
+}
+
+// RequestFromContext returns the Request previously stashed by WithHTTP, or
+// nil outside an HTTP-served dispatch.
+func RequestFromContext(ctx context.Context) *http.Request {
+	r, _ := ctx.Value(requestContextKey).(*http.Request)
+	return r
+}

extensions/dashboard/aware.go

@@ -1,6 +1,8 @@
 package dashboard
 
 import (
+	"github.com/xraph/forge/extensions/dashboard/contract"
+	"github.com/xraph/forge/extensions/dashboard/contract/dispatcher"
 	"github.com/xraph/forge/extensions/dashboard/contributor"
 	"github.com/xraph/forge/extensions/dashboard/ui/shell"
 	"github.com/xraph/forgeui/bridge"
@@ -52,6 +54,43 @@ type BridgeAware interface {
 //	    ext.SetAuthChecker(myAuthChecker)
 //	    ext.EnableAuth()
 //	}
+//
+// Slice (l) note — wiring an auth extension into the contract React shell:
+//
+// The dashboard shell ships a built-in LoginScreen that submits a contract
+// command (default `auth.login`) and reloads the principal on success. Auth
+// extensions can plug in by implementing both DashboardAuthAware *and*
+// ContractContributorAware:
+//
+//   - DashboardAuthAware.RegisterDashboardAuth wires the AuthChecker so
+//     /api/dashboard/v1/principal returns the current user. The shell's
+//     AuthGate listens for the 401 envelope (auth required) vs the 200
+//     `{authenticated:false}` envelope (auth disabled) and renders the
+//     LoginScreen only in the former case.
+//   - ContractContributorAware.RegisterContractContributor registers the
+//     `auth.login` command intent (and optionally `auth.logout`) on the
+//     dispatcher. The built-in LoginScreen issues the command; an
+//     extension that wants a richer flow can also publish a `/login`
+//     graph route in its manifest, and the shell's AuthGate will render
+//     that page instead of the built-in form.
+//
+// Example combined integration sketch:
+//
+//	func (a *AuthsomeExtension) RegisterDashboardAuth(ext *dashboard.Extension) {
+//	    ext.SetAuthChecker(a.checker)
+//	    ext.EnableAuth()
+//	}
+//	func (a *AuthsomeExtension) RegisterContractContributor(
+//	    disp *dispatcher.Dispatcher,
+//	    reg contract.Registry,
+//	    wreg contract.WardenRegistry,
+//	) error {
+//	    return authsomecontract.Register(disp, reg, wreg, authsomecontract.Deps{
+//	        Sessions: a.sessions,
+//	        // Registers `auth.login` (command) and optionally a `/login`
+//	        // graph route that overrides the built-in LoginScreen.
+//	    })
+//	}
 type DashboardAuthAware interface {
 	RegisterDashboardAuth(ext *Extension)
 }
@@ -72,3 +111,35 @@ type DashboardAuthAware interface {
 type DashboardFooterContributor interface {
 	DashboardUserDropdownActions(basePath string) []shell.UserDropdownAction
 }
+
+// ContractContributorAware is an optional interface that Forge extensions can
+// implement to register a contract-based dashboard contributor (the slice (f)+
+// shape — declarative YAML manifest + typed dispatcher handlers). The
+// dashboard auto-discovers extensions implementing this interface during
+// Start() and calls RegisterContractContributor with the dashboard's contract
+// registry, warden registry, and dispatcher.
+//
+// Coexists with DashboardAware: an extension can implement both to register
+// its legacy templ-based contributor AND its contract contributor during the
+// migration window. New extensions should prefer this interface; legacy ones
+// migrate over time per the per-slice (f, g, h) plan.
+//
+// Example implementation:
+//
+//	func (e *StreamingExtension) RegisterContractContributor(
+//	    disp *dispatcher.Dispatcher,
+//	    reg contract.Registry,
+//	    wreg contract.WardenRegistry,
+//	) error {
+//	    return streamingcontract.Register(disp, reg, wreg, streamingcontract.Deps{
+//	        Manager: func() streaming.Manager { return e.manager },
+//	        Config:  func() streaming.Config { return e.config },
+//	    })
+//	}
+type ContractContributorAware interface {
+	RegisterContractContributor(
+		disp *dispatcher.Dispatcher,
+		reg contract.Registry,
+		wreg contract.WardenRegistry,
+	) error
+}

extensions/dashboard/config.go

@@ -53,12 +53,22 @@ type Config struct {
 	// Security
 	EnableCSP  bool `json:"enable_csp"  yaml:"enable_csp"`
 	EnableCSRF bool `json:"enable_csrf" yaml:"enable_csrf"`
+	// EnableContractSecurity gates CSRF validation, idempotency dedup, and
+	// distributed tracing on the contract envelope endpoint. Default true;
+	// set to false during a rollout window where clients have not yet
+	// adopted CSRF tokens or the idempotency-key contract.
+	EnableContractSecurity bool `json:"enable_contract_security" yaml:"enable_contract_security"`
 
 	// Authentication
 	EnableAuth    bool   `json:"enable_auth"    yaml:"enable_auth"`    // enable auth support
 	LoginPath     string `json:"login_path"     yaml:"login_path"`     // relative auth login path (e.g. "/auth/login")
 	LogoutPath    string `json:"logout_path"    yaml:"logout_path"`    // relative auth logout path (e.g. "/auth/logout")
 	DefaultAccess string `json:"default_access" yaml:"default_access"` // "public", "protected", "partial"
+	// RequiredRoles, when non-empty, restricts dashboard access to users
+	// carrying at least one matching role. The principal endpoint surfaces
+	// 403 PERMISSION_DENIED to the React shell for users who don't qualify;
+	// the shell renders an "access denied" panel instead of the dashboard.
+	RequiredRoles []string `json:"required_roles" yaml:"required_roles"`
 
 	// Theming
 	Theme     string `json:"theme"      yaml:"theme"` // light, dark, auto
@@ -101,8 +111,9 @@ func DefaultConfig() Config {
 
 		SSEKeepAlive: 15 * time.Second,
 
-		EnableCSP:  true,
-		EnableCSRF: true,
+		EnableCSP:              true,
+		EnableCSRF:             true,
+		EnableContractSecurity: true,
 
 		EnableAuth:    false,
 		LoginPath:     "/login",
@@ -255,6 +266,14 @@ func WithCSRF(enabled bool) ConfigOption {
 	return func(c *Config) { c.EnableCSRF = enabled }
 }
 
+// WithContractSecurity enables or disables the contract envelope's
+// security stack (CSRF validation, idempotency dedup, request tracing).
+// Defaults to true; switching off should be reserved for rollout windows
+// where clients have not yet adopted CSRF tokens or idempotency keys.
+func WithContractSecurity(enabled bool) ConfigOption {
+	return func(c *Config) { c.EnableContractSecurity = enabled }
+}
+
 // WithTheme sets the UI theme (light, dark, auto).
 func WithTheme(theme string) ConfigOption {
 	return func(c *Config) { c.Theme = theme }
@@ -285,6 +304,15 @@ func WithEnableAuth(enabled bool) ConfigOption {
 	return func(c *Config) { c.EnableAuth = enabled }
 }
 
+// WithRequiredRoles restricts dashboard access to users carrying at least
+// one of the given roles. Pass nil/empty to allow all authenticated users.
+// Auth extensions (e.g. authsome) call this via Extension.SetRequiredRoles
+// when their config declares a role gate; deployments can also configure
+// it directly via this option.
+func WithRequiredRoles(roles []string) ConfigOption {
+	return func(c *Config) { c.RequiredRoles = append([]string(nil), roles...) }
+}
+
 // WithLoginPath sets the relative login page path (e.g. "/auth/login").
 func WithLoginPath(path string) ConfigOption {
 	return func(c *Config) { c.LoginPath = path }