Migrate API to typed Huma routes (#599)

The API migration needed to stop carrying two parallel contracts: typed Huma handlers on the server and hand-assembled frontend request paths in the UI. That split made enums, request bodies, response shapes, and error handling easy to drift, and review feedback showed the first migration pass still left some runtime parity and generated-client boundary gaps.

This PR moves the server API onto grouped typed Huma route registration, exposes OpenAPI 3.1 for introspection, generates the frontend TypeScript client from that contract, and routes normal JSON frontend calls through generated services. Streaming, import, and download paths stay explicit where the generated JSON abstraction is not appropriate.

It also addresses review follow-ups around route-group ownership, generated-code metadata, import response content types, secret-scan SSE parity, and generated-client error normalization.

Validation performed locally:
- go test -count=1 ./...
- npm run generate:api
- npm run check
- npm test -- --run
- git diff --check


Co-authored-by: Marius van Niekerk <mariusvniekerk@users.noreply.github.com>

Author: mariusvniekerk

.gitattributes

@@ -0,0 +1,2 @@
+# OpenAPI TypeScript client generated by frontend/scripts/generate-api-client.mjs.
+frontend/src/lib/api/generated/** linguist-generated=true

.kata.toml

@@ -0,0 +1,4 @@
+version = 1
+
+[project]
+name = "agentsview"

cmd/agentsview/cli.go

@@ -10,6 +10,7 @@ import (
 	"github.com/spf13/cobra"
 	"go.kenn.io/agentsview/internal/config"
 	"go.kenn.io/agentsview/internal/db"
+	"go.kenn.io/agentsview/internal/server"
 	"golang.org/x/term"
 )
 
@@ -69,6 +70,7 @@ func newRootCommand() *cobra.Command {
 	root.AddCommand(newClassifierCommand())
 	root.AddCommand(newSecretsCommand())
 	root.AddCommand(newVersionCommand())
+	root.AddCommand(newOpenAPICommand())
 
 	defaultHelp := root.HelpFunc()
 	root.SetHelpFunc(func(cmd *cobra.Command, args []string) {
@@ -97,6 +99,28 @@ func newServeCommand() *cobra.Command {
 	return cmd
 }
 
+func newOpenAPICommand() *cobra.Command {
+	return &cobra.Command{
+		Use:          "openapi",
+		Short:        "Print OpenAPI 3.1 schema",
+		GroupID:      groupMeta,
+		SilenceUsage: true,
+		Args:         cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			spec, err := server.OpenAPIJSON(server.VersionInfo{
+				Version:   version,
+				Commit:    commit,
+				BuildDate: buildDate,
+			})
+			if err != nil {
+				return err
+			}
+			_, err = cmd.OutOrStdout().Write(append(spec, '\n'))
+			return err
+		},
+	}
+}
+
 func newSyncCommand() *cobra.Command {
 	var cfg SyncConfig
 	cmd := &cobra.Command{

cmd/agentsview/cli_test.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"bytes"
+	"encoding/json"
 	"os"
 	"testing"
 
@@ -52,6 +53,22 @@ func TestRootHelpShowsKeySectionsAndCommands(t *testing.T) {
 	}
 }
 
+func TestOpenAPICommandEmitsSpec(t *testing.T) {
+	out, err := executeCommand(newRootCommand(), "openapi")
+	require.NoError(t, err, "Execute")
+
+	var spec struct {
+		OpenAPI string                    `json:"openapi"`
+		Paths   map[string]map[string]any `json:"paths"`
+	}
+	require.NoError(t, json.Unmarshal([]byte(out), &spec))
+	assert.Equal(t, "3.1.0", spec.OpenAPI)
+	require.Contains(t, spec.Paths, "/api/v1/sessions")
+	assert.Contains(t, spec.Paths["/api/v1/sessions"], "get")
+	require.Contains(t, spec.Paths, "/api/v1/sessions/{id}/rename")
+	assert.Contains(t, spec.Paths["/api/v1/sessions/{id}/rename"], "patch")
+}
+
 func TestRootNoArgsShowsHelp(t *testing.T) {
 	out, err := executeCommand(newRootCommand())
 	require.NoError(t, err, "Execute")

docs/huma-api-routes.md

@@ -0,0 +1,29 @@
+# Huma API Routes
+
+The server API is registered with Huma route groups. Keep each route group
+self-contained so OpenAPI ownership stays close to runtime behavior.
+
+## File Ownership
+
+- Put route registration, endpoint-specific input types, response wrapper
+  types, enums, and handlers in the route group file that owns the path.
+- Keep `internal/server/huma_routes.go` limited to shared Huma plumbing:
+  API configuration, route registration helpers, common path/query inputs,
+  error conversion, schema naming, SSE/write helpers, and middleware.
+- Move a helper into shared plumbing only when at least two route groups use
+  it and it has no domain-specific policy.
+- Do not add new typed handlers to a catch-all API file. Add a new group file
+  when a new API area does not fit an existing group.
+
+## Compatibility Guardrails
+
+When changing route registration or generated client contracts:
+
+- Preserve existing paths, methods, status codes, response events, and content
+  types unless the change is intentional and covered by tests.
+- Add or update parity tests for JSON bodies, raw downloads, multipart imports,
+  SSE terminal events, and error responses touched by the change.
+- Run `npm run generate:api` from `frontend/` and verify generated output only
+  changes when the OpenAPI contract intentionally changed.
+- Keep generated frontend code under `frontend/src/lib/api/generated/`; it is
+  marked as generated in `.gitattributes` and should not be hand-edited.