feat(figma): Figma in API endpoints, screenshot hosting (Phase F — T4F.1, T4F.2)

.env.example

@@ -26,7 +26,7 @@ BAUER_CREDENTIALS_PATH=/path/to/service-account.json
 # --- Figma integration (optional; required when --figma-url is supplied) ---
 BAUER_FIGMA_TOKEN=figd_xxxxxxxxxxxxx
 # FIGMA_TOKEN=figd_xxxxxxxxxxxxx  (fallback if BAUER_FIGMA_TOKEN not set)
-BAUER_FIGMA_URL=  # e.g. https://www.figma.com/file/AbCdEfGhIjKl/Design?node-id=1:42
+BAUER_FIGMA_URL= # e.g. https://www.figma.com/file/AbCdEfGhIjKl/Design?node-id=1:42
 
 # --- API Server ---
 BAUER_API_PORT=8090
@@ -42,3 +42,8 @@ BAUER_PAGE_REFRESH=false
 BAUER_ARTIFACTS_DIR=./bauer-artifacts
 BAUER_BRANCH_PREFIX=bauer
 BAUER_DRY_RUN=false
+
+# --- Screenshot hosting (T4F.2) ---
+BAUER_STATIC_BASE_URL= # Public URL prefix for serving screenshots (e.g. https://bauer.example.com/static)
+BAUER_S3_BUCKET= # S3 bucket for screenshot hosting (NOT YET IMPLEMENTED — setting this will cause errors)
+BAUER_S3_REGION= # AWS region for S3 bucket

Taskfile.yml

@@ -66,15 +66,15 @@ tasks:
     desc: Run the Bauer API locally in Docker (reads .env.local for secrets)
     cmds:
       - docker run -p 8090:8090
-          --env-file .env.local
-          -v "${BAUER_CREDENTIALS_PATH}:/creds/service-account.json:ro"
-          -e BAUER_CREDENTIALS_PATH=/creds/service-account.json
-          bauer-api:latest
+        --env-file .env.local
+        -v "${BAUER_CREDENTIALS_PATH}:/creds/service-account.json:ro"
+        -e BAUER_CREDENTIALS_PATH=/creds/service-account.json
+        bauer-api:latest
 
   clean:
     desc: Clean up generated files
     cmds:
       - rm -rf bauer-output
       - rm -f bauer bauer-api
       - rm -f bauer.log
-      - rm -rf /tmp/gh* /tmp/tmp* /tmp/test-bauer-repo* || true
+      - rm -rf /tmp/gh* /tmp/tmp* /tmp/test-bauer-repo* || true

cmd/app/main.go

@@ -14,6 +14,7 @@ import (
 	"log/slog"
 	"net/http"
 	"os"
+	"path/filepath"
 
 	"github.com/joho/godotenv"
 )
@@ -67,6 +68,14 @@ func run() error {
 	protected.HandleFunc("POST /api/v1/webhooks/jira", v1.JiraWebhookHandler(cfg))
 
 	mux.Handle("/api/v1/", auth.JWTMiddleware(protected))
+
+	// Serve artifact screenshots at /static/ when BAUER_STATIC_BASE_URL is configured.
+	if baseURL := os.Getenv("BAUER_STATIC_BASE_URL"); baseURL != "" {
+		screenshotsDir := filepath.Join(cfg.ArtifactsDir, "screenshots")
+		slog.Info("Serving artifact screenshots at /static/", slog.String("base_url", baseURL), slog.String("dir", screenshotsDir))
+		mux.Handle("/static/", http.StripPrefix("/static/", http.FileServer(http.Dir(screenshotsDir))))
+	}
+
 	slog.Info("starting server", "address", ":8090")
 	err = http.ListenAndServe(":8090", middleware.RequestTrace(mux))
 
@@ -86,4 +95,3 @@ func main() {
 		os.Exit(1)
 	}
 }
-

cmd/app/v1/api.go

@@ -86,7 +86,6 @@ func executeJob(requestID string, cfg config.Config, rc types.RouteConfig) {
 	)
 }
 
-
 func GetHealth(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(http.StatusOK)
@@ -134,4 +133,4 @@ func ReadinessHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	json.NewEncoder(w).Encode(map[string]any{"status": "ready"})
-}
+}

cmd/app/v1/issues.go

@@ -1,8 +1,10 @@
 package v1
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
+	"log/slog"
 	"net/http"
 	"os"
 	"strings"
@@ -71,7 +73,7 @@ func IssuesHandler(apiCfg *types.APIConfig) http.HandlerFunc {
 		cfg.ApplyDefaults()
 
 		sources := source.NewManager(cfg.CredentialsPath)
-		arts := artifacts.NewManager(firstNonEmpty(os.Getenv("BAUER_ARTIFACTS_DIR"), "./bauer-artifacts"))
+		arts := artifacts.NewManager(apiCfg.ArtifactsDir)
 		copilotAgent, err := copilotcli.NewClient(os.TempDir())
 		if err != nil {
 			httpError(w, http.StatusInternalServerError, "failed to create copilot client")
@@ -93,7 +95,14 @@ func IssuesHandler(apiCfg *types.APIConfig) http.HandlerFunc {
 		repoFull := parts[0] + "/" + parts[1]
 
 		title := fmt.Sprintf("BAU: Apply suggestions from doc %s", req.DocID)
-		body := formatIssueBody(result, req.DocID)
+
+		artsDir := apiCfg.ArtifactsDir
+		host := artifacts.HostFromEnv(artsDir)
+		if _, isNop := host.(*artifacts.NopHost); isNop && req.FigmaURL != "" {
+			slog.Warn("BAUER_STATIC_BASE_URL not set; issue body will contain local screenshot paths",
+				slog.String("run_id", result.RunID))
+		}
+		body := formatIssueBodyWithHosting(r.Context(), result, req.DocID, host)
 
 		issueURL, issueNum, err := github.CreateIssue(r.Context(), token, repoFull, title, body)
 		if err != nil {
@@ -110,6 +119,17 @@ func IssuesHandler(apiCfg *types.APIConfig) http.HandlerFunc {
 	}
 }
 
+func formatIssueBodyWithHosting(ctx context.Context, result *orchestrator.OrchestrationResult, docID string, host artifacts.ScreenshotHost) string {
+	body := formatIssueBody(result, docID)
+	// When a real hosting backend is configured, screenshot paths embedded in the
+	// issue body can be rewritten to public URLs here. For now, the body is
+	// returned as-is; the NopHost leaves local paths unchanged, and callers
+	// are warned via slog when no hosting backend is set.
+	_ = host
+	_ = ctx
+	return body
+}
+
 func formatIssueBody(result *orchestrator.OrchestrationResult, docID string) string {
 	var sb strings.Builder
 	sb.WriteString("## BAU Documentation Improvement Plan\n\n")

cmd/app/v1/jira.go

@@ -64,7 +64,11 @@ func JiraWebhookHandler(apiCfg *types.APIConfig) http.HandlerFunc {
 
 			sources := source.NewManager(cfg.CredentialsPath)
 			arts := artifacts.NewManager(firstNonEmpty(os.Getenv("BAUER_ARTIFACTS_DIR"), "./bauer-artifacts"))
-			agent, _ := copilotcli.NewClient(os.TempDir())
+			agent, err := copilotcli.NewClient(os.TempDir())
+			if err != nil {
+				slog.Error("failed to create copilot agent", "error", err)
+				return
+			}
 			orch := orchestrator.New(agent, sources, arts)
 			if _, err := orch.Execute(context.Background(), cfg); err != nil {
 				slog.Error("Jira webhook workflow failed",

cmd/bauer/main.go

@@ -31,7 +31,10 @@ func main() {
 	openIssue := fs.Bool("open-issue", false, "Generate a plan and open a GitHub issue without applying changes (mutually exclusive with --open-pr)")
 	branchPrefix := fs.String("branch-prefix", "", "Prefix for created branches (default: bauer)")
 	githubRepo := fs.String("github-repo", "", "GitHub repository in owner/repo format (required for --open-pr and --open-issue)")
-        figmaURL := fs.String("figma-url", "", "Figma file or design URL for design reference (requires BAUER_FIGMA_TOKEN)")
+	figmaURL := fs.String("figma-url", "", "Figma file or design URL for design reference (requires BAUER_FIGMA_TOKEN)")
+
+	fs.Usage = func() {
+		fmt.Fprintf(os.Stderr, "Usage: %s [flags]\n\n", os.Args[0])
 		fmt.Fprintf(os.Stderr, "Flags:\n\n")
 		fs.PrintDefaults()
 		fmt.Fprintf(os.Stderr, "\nEnvironment variables:\n\n")
@@ -44,7 +47,8 @@ func main() {
 		fmt.Fprintf(os.Stderr, "\tBAUER_ARTIFACTS_DIR             Override for --artifacts-dir\n")
 		fmt.Fprintf(os.Stderr, "\tBAUER_BRANCH_PREFIX             Override for --branch-prefix\n")
 		fmt.Fprintf(os.Stderr, "\tBAUER_GITHUB_REPO               Override for --github-repo\n")
-                fmt.Fprintf(os.Stderr, "\tBAUER_FIGMA_TOKEN               Figma API token (required when --figma-url is supplied)\n")
+		fmt.Fprintf(os.Stderr, "\tBAUER_FIGMA_TOKEN               Figma API token (required when --figma-url is supplied)\n")
+	}
 
 	if err := fs.Parse(os.Args[1:]); err != nil {
 		os.Exit(1)