chores: code clean up, linter fix, security improvement

Author: irahardianto

.gitignore

@@ -5,6 +5,7 @@ Thumbs.db
 *.log
 tmp/
 temp/
+.agent/
 
 # IDEs
 .idea/

README.md

@@ -109,7 +109,7 @@ Configuration is managed via the **Settings** page in the UI or environment vari
 
 > [!TIP]
 > **Unlock the full potential of your Agent**<br>
-> Check out the **[Agent Prompting Guide](docs/agent.md)** for best practices, workflow examples, and **system prompt templates** (`CLAUDE.md`, `GEMINI.md`) to paste into your project.
+> Check out the **[Agent Prompting Guide](docs/agent-prompting-guide.md)** for best practices, workflow examples, and **system prompt templates** (`CLAUDE.md`, `GEMINI.md`) to paste into your project.
 
 ### 1. Add Data Sources
 Navigate to the Admin Dashboard ([http://localhost:3000](http://localhost:3000)) and click **"Add Source"**.

apps/backend/features/job/handler.go

@@ -41,7 +41,9 @@ func (h *Handler) List(w http.ResponseWriter, r *http.Request) {
 		"data": jobs,
 		"meta": map[string]int{"count": len(jobs)},
 	}
-	json.NewEncoder(w).Encode(resp)
+	if err := json.NewEncoder(w).Encode(resp); err != nil {
+		slog.ErrorContext(ctx, "failed to encode response", "error", err)
+	}
 }
 
 func (h *Handler) Retry(w http.ResponseWriter, r *http.Request) {
@@ -63,7 +65,9 @@ func (h *Handler) Retry(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(http.StatusOK)
-	json.NewEncoder(w).Encode(map[string]interface{}{"data": "job retried"})
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{"data": "job retried"}); err != nil {
+		slog.ErrorContext(ctx, "failed to encode response", "error", err)
+	}
 }
 
 func (h *Handler) writeError(ctx context.Context, w http.ResponseWriter, code, message string, status int) {
@@ -78,5 +82,7 @@ func (h *Handler) writeError(ctx context.Context, w http.ResponseWriter, code, m
 		"correlationId": middleware.GetCorrelationID(ctx),
 	}
 
-	json.NewEncoder(w).Encode(resp)
+	if err := json.NewEncoder(w).Encode(resp); err != nil {
+		slog.Error("failed to encode error response", "error", err)
+	}
 }

apps/backend/features/job/handler_test.go

@@ -23,24 +23,28 @@ func (m *MockRepo) Save(ctx context.Context, j *job.Job) error {
 	args := m.Called(ctx, j)
 	return args.Error(0)
 }
+
 func (m *MockRepo) List(ctx context.Context) ([]job.Job, error) {
 	args := m.Called(ctx)
 	if args.Get(0) == nil {
 		return nil, args.Error(1)
 	}
 	return args.Get(0).([]job.Job), args.Error(1)
 }
+
 func (m *MockRepo) Get(ctx context.Context, id string) (*job.Job, error) {
 	args := m.Called(ctx, id)
 	if args.Get(0) == nil {
 		return nil, args.Error(1)
 	}
 	return args.Get(0).(*job.Job), args.Error(1)
 }
+
 func (m *MockRepo) Delete(ctx context.Context, id string) error {
 	args := m.Called(ctx, id)
 	return args.Error(0)
 }
+
 func (m *MockRepo) Count(ctx context.Context) (int, error) {
 	args := m.Called(ctx)
 	return args.Int(0), args.Error(1)
@@ -111,4 +115,4 @@ func TestHandler_Retry(t *testing.T) {
 	assert.Equal(t, http.StatusOK, w.Result().StatusCode)
 	mockRepo.AssertExpectations(t)
 	mockPub.AssertExpectations(t)
-}
+}

apps/backend/features/job/repo_integration_test.go

@@ -2,14 +2,14 @@ package job_test
 
 import (
 	"context"
+	"database/sql"
 	"encoding/json"
 	"testing"
 	"time"
-	"database/sql"
 
+	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"github.com/google/uuid"
 	"qurio/apps/backend/features/job"
 	"qurio/apps/backend/features/source"
 	"qurio/apps/backend/internal/testutils"
@@ -75,7 +75,7 @@ func TestJobRepo_Integration(t *testing.T) {
 	// 5. Verify Delete
 	err = jobRepo.Delete(ctx, j1.ID)
 	require.NoError(t, err)
-	
+
 	// Verify it's gone
 	_, err = jobRepo.Get(ctx, j1.ID)
 	assert.Error(t, err)
@@ -96,7 +96,9 @@ func TestJobRepo_Integration(t *testing.T) {
 }
 
 func TestJobRepo_Empty(t *testing.T) {
-	if testing.Short() { t.Skip() }
+	if testing.Short() {
+		t.Skip()
+	}
 	s := testutils.NewIntegrationSuite(t)
 	s.Setup()
 	defer s.Teardown()
@@ -114,7 +116,9 @@ func TestJobRepo_Empty(t *testing.T) {
 }
 
 func TestJobRepo_Get_NotFound(t *testing.T) {
-	if testing.Short() { t.Skip() }
+	if testing.Short() {
+		t.Skip()
+	}
 	s := testutils.NewIntegrationSuite(t)
 	s.Setup()
 	defer s.Teardown()
@@ -125,4 +129,4 @@ func TestJobRepo_Get_NotFound(t *testing.T) {
 	_, err := jobRepo.Get(ctx, uuid.NewString())
 	assert.Error(t, err)
 	assert.Equal(t, sql.ErrNoRows, err)
-}
+}

apps/backend/features/job/repo_test.go

@@ -2,10 +2,10 @@ package job_test
 
 import (
 	"context"
+	"encoding/json"
 	"regexp"
 	"testing"
 	"time"
-	"encoding/json"
 
 	"github.com/DATA-DOG/go-sqlmock"
 	"github.com/stretchr/testify/assert"

apps/backend/features/job/service_test.go

@@ -50,7 +50,7 @@ func TestRetry_Timeout(t *testing.T) {
 	// though not ideal for fast unit tests.
 	// Alternatively, I can't easily mock `time.After` without dependency injection.
 	// I'll proceed with the 6s sleep for correctness verification as per plan "Verify test passes".
-	
+
 	err := service.Retry(context.Background(), "1")
 	if err == nil {
 		t.Fatal("Expected timeout error, got nil")
@@ -113,20 +113,20 @@ func (m *MockJobRepoForTopic) Get(ctx context.Context, id string) (*Job, error)
 	return &Job{ID: id, Payload: m.Payload}, nil
 }
 func (m *MockJobRepoForTopic) Delete(ctx context.Context, id string) error { return nil }
-func (m *MockJobRepoForTopic) List(ctx context.Context) ([]Job, error) { return nil, nil }
-func (m *MockJobRepoForTopic) Count(ctx context.Context) (int, error) { return 0, nil }
-func (m *MockJobRepoForTopic) Save(ctx context.Context, job *Job) error { return nil }
+func (m *MockJobRepoForTopic) List(ctx context.Context) ([]Job, error)     { return nil, nil }
+func (m *MockJobRepoForTopic) Count(ctx context.Context) (int, error)      { return 0, nil }
+func (m *MockJobRepoForTopic) Save(ctx context.Context, job *Job) error    { return nil }
 
 func TestRetry_TopicSelection(t *testing.T) {
 	pub := &MockPublisher{}
 	logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
-	
+
 	// We need to inject the specific repo behavior.
 	// Since NewService takes Repository interface, we can pass our custom mock.
 	customRepo := &MockJobRepoForTopic{
 		Payload: []byte(`{"type": "file", "path": "/tmp/test.pdf"}`),
 	}
-	
+
 	service := NewService(customRepo, pub, logger)
 
 	err := service.Retry(context.Background(), "1")

apps/backend/features/mcp/handler.go

@@ -23,8 +23,8 @@ type SourceManager interface {
 }
 
 type Handler struct {
-	retriever    Retriever
-	sourceMgr    SourceManager
+	retriever Retriever
+	sourceMgr SourceManager
 }
 
 func NewHandler(r Retriever, s SourceManager) *Handler {
@@ -127,7 +127,7 @@ func (h *Handler) processRequest(ctx context.Context, req JSONRPCRequest) *JSONR
 			Result: ListToolsResult{
 				Tools: []Tool{
 					{
-						Name:        "qurio_search",
+						Name: "qurio_search",
 						Description: `Search & Exploration tool. Performs a hybrid search (Keyword + Vector). Use this for specific questions, finding code snippets, or exploring topics across known sources.
 
 ARGUMENT GUIDE:
@@ -183,7 +183,7 @@ USAGE EXAMPLES:
 						},
 					},
 					{
-						Name:        "qurio_list_sources",
+						Name: "qurio_list_sources",
 						Description: `Discovery tool. Lists all available documentation sets (sources) currently indexed. Use this at the start of a session to understand what documentation is available.
 
 USAGE EXAMPLE:
@@ -194,7 +194,7 @@ qurio_list_sources()`,
 						},
 					},
 					{
-						Name:        "qurio_list_pages",
+						Name: "qurio_list_pages",
 						Description: `Navigation tool. Lists all individual pages/documents within a specific source. Use this to find the exact URL of a document when a search query is too broad or to browse the table of contents.
 
 USAGE EXAMPLE:
@@ -211,7 +211,7 @@ qurio_list_pages(source_id="src_stripe_api")`,
 						},
 					},
 					{
-						Name:        "qurio_read_page",
+						Name: "qurio_read_page",
 						Description: `Deep Reading / Full Context tool. Retrieves the *entire* content of a specific page or document by its URL. Use this when a search result snippet is truncated or insufficient, or when you need to read a full guide/tutorial. Crucial: Always prefer this over guessing content if the search result is incomplete.
 
 USAGE EXAMPLE:
@@ -256,7 +256,7 @@ read_page(url="https://docs.stripe.com/webhooks/signatures")`,
 				resp := makeErrorResponse(req.ID, ErrInvalidParams, "Invalid search arguments")
 				return &resp
 			}
-			
+
 			if args.Query == "" {
 				resp := makeErrorResponse(req.ID, ErrInvalidParams, "Query is required")
 				return &resp
@@ -285,7 +285,7 @@ read_page(url="https://docs.stripe.com/webhooks/signatures")`,
 				resp := makeErrorResponse(req.ID, ErrInternal, "Search failed: "+err.Error())
 				return &resp
 			}
-			
+
 			var textResult string
 			if len(results) == 0 {
 				textResult = "No results found."
@@ -305,21 +305,21 @@ read_page(url="https://docs.stripe.com/webhooks/signatures")`,
 					if res.SourceID != "" {
 						textResult += fmt.Sprintf("SourceID: %s\n", res.SourceID)
 					}
-					
+
 					textResult += fmt.Sprintf("Content:\n%s\n", res.Content)
-					
+
 					// Optional: Show other metadata
 					// if len(res.Metadata) > 0 {
 					// 	meta, _ := json.Marshal(res.Metadata)
 					// 	txtResult += fmt.Sprintf("Metadata: %s\n", string(meta))
 					// }
 					textResult += "\n---\n"
 				}
-				
+
 				textResult += "\nUse qurio_read_page(url=\"...\") to read the full content of any result.\n"
 			}
 
-			slog.Info("tool execution completed", "tool", "qurio_search", "result_count", len(results))
+			slog.Info("tool execution completed", "tool", "qurio_search", "result_count", len(results)) // #nosec G706 -- len() result is int, not tainted
 
 			return &JSONRPCResponse{
 				JSONRPC: "2.0",
@@ -364,7 +364,7 @@ read_page(url="https://docs.stripe.com/webhooks/signatures")`,
 				Type string `json:"type"`
 				URL  string `json:"url"`
 			}
-			
+
 			simpleSources := make([]SimpleSource, len(sources))
 			for i, s := range sources {
 				name := s.Name
@@ -413,7 +413,7 @@ read_page(url="https://docs.stripe.com/webhooks/signatures")`,
 				resp := makeErrorResponse(req.ID, ErrInvalidParams, "Invalid arguments")
 				return &resp
 			}
-			
+
 			if args.SourceID == "" {
 				resp := makeErrorResponse(req.ID, ErrInvalidParams, "source_id is required")
 				return &resp
@@ -448,7 +448,7 @@ read_page(url="https://docs.stripe.com/webhooks/signatures")`,
 				ID  string `json:"id"`
 				URL string `json:"url"`
 			}
-			
+
 			simplePages := make([]SimplePage, len(pages))
 			for i, p := range pages {
 				simplePages[i] = SimplePage{
@@ -488,7 +488,7 @@ read_page(url="https://docs.stripe.com/webhooks/signatures")`,
 				resp := makeErrorResponse(req.ID, ErrInvalidParams, "Invalid arguments")
 				return &resp
 			}
-			
+
 			if args.URL == "" {
 				resp := makeErrorResponse(req.ID, ErrInvalidParams, "URL is required")
 				return &resp
@@ -525,7 +525,7 @@ read_page(url="https://docs.stripe.com/webhooks/signatures")`,
 				}
 			}
 
-			slog.Info("tool execution completed", "tool", "qurio_read_page", "chunk_count", len(results))
+			slog.Info("tool execution completed", "tool", "qurio_read_page", "chunk_count", len(results)) // #nosec G706 -- len() result is int, not tainted
 
 			return &JSONRPCResponse{
 				JSONRPC: "2.0",
@@ -537,12 +537,12 @@ read_page(url="https://docs.stripe.com/webhooks/signatures")`,
 				},
 			}
 		}
-		
+
 		slog.Warn("method not found", "method", params.Name)
 		resp := makeErrorResponse(req.ID, ErrMethodNotFound, "Method not found: "+params.Name)
 		return &resp
 	}
-	
+
 	slog.Warn("unknown jsonrpc method", "method", req.Method)
 	resp := makeErrorResponse(req.ID, ErrMethodNotFound, "Method not found")
 	return &resp
@@ -560,7 +560,7 @@ func makeErrorResponse(id interface{}, code int, message string) JSONRPCResponse
 }
 
 func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	slog.Info("mcp request received", "method", r.Method, "path", r.URL.Path)
+	slog.Info("mcp request received", "method", r.Method, "path", r.URL.Path) // #nosec G706 -- r.URL.Path is parsed by Go's net/http, not raw user input
 
 	w.Header().Set("Content-Type", "application/json")
 
@@ -597,7 +597,7 @@ func (h *Handler) writeError(w http.ResponseWriter, id interface{}, code int, me
 	// However, the helper above `writeError` was defined at file level? No, it's a method.
 	// Let's check if it's already defined in this file. It was in the previous version.
 	// I will just call it.
-	
+
 	resp := makeErrorResponse(id, code, message)
 	if err := json.NewEncoder(w).Encode(resp); err != nil {
 		slog.Error("failed to write error response", "error", err)