feat: Bootstrap project with Fx, Makefile and GitHub Actions

hashkode · hashkode · commit 710a6ba0da8f · 2025-04-07T22:36:35.000+02:00
Establishes the initial Go project structure using Fx for dependency injection and lifecycle management. Includes foundational tooling and CI/CD setup.

- Initializes core directory structure (cmd, internal, scripts, .github).
- Integrates Uber Fx framework in main.go and internal/app.
- Sets up zerolog logging with an Fx adapter (internal/log).
- Creates a Makefile with targets for common tasks (build, run, test, fmt, lint, setup, tidy).
- Adds a setup script (scripts/setup.sh) to install tools (templ, golangci-lint) and check PATH.
- Configures GitHub Actions workflows for:
    - Go build/test/lint/format (go.yaml)
    - MegaLinter checks (mega-linter.yaml)
    - Semantic Release (release.yaml)
- Adds comprehensive README with setup, usage and CI details.
- Includes .gitignore file to avoid bloat.
- Adds a dummy test (internal/app/app_test.go) to validate test execution.
diff --git a/.github/workflows/go.yaml b/.github/workflows/go.yaml
@@ -0,0 +1,45 @@
+---
+name: Go CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    name: Build & Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21' # Or your desired Go version
+
+      - name: Setup tools
+        run: make setup
+
+      - name: Tidy modules
+        run: make tidy
+
+      - name: Check formatting
+        run: |
+          make fmt
+          # Check if git status is clean after formatting
+          if ! git diff --exit-code; then
+            echo "Code is not formatted correctly. Run 'make fmt' locally."
+            exit 1
+          fi
+
+      - name: Lint code
+        run: make lint
+
+      - name: Run tests
+        run: make test
+
+      - name: Build application
+        run: make build 
diff --git a/.github/workflows/mega-linter.yaml b/.github/workflows/mega-linter.yaml
@@ -0,0 +1,58 @@
+---
+  # MegaLinter GitHub Action configuration file
+  # More info at https://megalinter.io
+  name: MegaLinter
+  
+  on:
+    push:
+      branches: [main]
+    pull_request:
+      branches: [main]
+  
+  permissions: read-all 
+  
+  env: # Comment env block if you don't want to apply fixes
+    # Apply linter fixes configuration
+    APPLY_FIXES: all # When active, APPLY_FIXES must also be defined as environment variable (in github/workflows/mega-linter.yml or other CI tool)
+    APPLY_FIXES_EVENT: none # Decide which event triggers application of fixes in a commit or a PR (pull_request, push, all)
+    APPLY_FIXES_MODE: commit # If APPLY_FIXES is used, defines if the fixes are directly committed (commit) or posted in a PR (pull_request)
+  
+  concurrency:
+    group: ${{ github.ref }}-${{ github.workflow }}
+    cancel-in-progress: true
+  
+  jobs:
+    megalinter:
+      name: MegaLinter
+      runs-on: ubuntu-latest
+      permissions:
+        contents: read
+        issues: write
+        pull-requests: write
+      steps:
+        # Git Checkout
+        - name: Checkout Code
+          uses: actions/checkout@v4
+          with:
+            token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
+            fetch-depth: 0 # If you use VALIDATE_ALL_CODEBASE = true, you can remove this line to improve performances
+        # MegaLinter
+        - name: MegaLinter
+          id: ml
+          # deployed v8.3.0, https://github.com/oxsecurity/megalinter/releases/tag/v8.3.0
+          uses: oxsecurity/megalinter@1fc052d03c7a43c78fe0fee19c9d648b749e0c01
+          env:
+            # All available variables are described in documentation
+            # https://megalinter.io/configuration/
+            VALIDATE_ALL_CODEBASE: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }} # Validates all source when push on main, else just the git diff with main. Override with true if you always want to lint all sources
+            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        # Upload MegaLinter artifacts
+        - name: Archive production artifacts
+          if: success() || failure()
+          uses: actions/upload-artifact@v4
+          with:
+            name: MegaLinter reports
+            path: |
+              megalinter-reports
+              mega-linter.log
+  
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -0,0 +1,28 @@
+---
+name: Tag and Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.SEMANTIC_RELEASE }}
+        run: npx semantic-release --branches main
diff --git a/.mega-linter.yml b/.mega-linter.yml
@@ -0,0 +1,17 @@
+---
+# Configuration file for MegaLinter
+# See all available variables at https://megalinter.io/configuration/ and in linters documentation
+
+DISABLE_LINTERS:
+  - SPELL_CSPELL
+  - SPELL_LYCHEE
+
+DISABLE_ERRORS_LINTERS:
+  - COPYPASTE_JSCPD
+  - REPOSITORY_DEVSKIM
+  - REPOSITORY_KICS
+
+EMAIL_REPORTER: false
+FILEIO_REPORTER: false
+MARKDOWN_SUMMARY_REPORTER: true
+SHOW_ELAPSED_TIME: true
diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: help build run test fmt lint generate tidy all
+.PHONY: help build run test fmt lint generate tidy setup
 
 # Default goal when 'make' is run without arguments
 .DEFAULT_GOAL := help
@@ -13,13 +13,18 @@ help:
 	@echo ""
 	@echo "Targets:"
 	@echo "  help       Show this help message (default)."
+	@echo "  setup      Install required tools (templ, golangci-lint)."
 	@echo "  build      Build the Go application binary into $(OUTPUT_DIR)/."
 	@echo "  run        Build and run the Go application from $(OUTPUT_DIR)/."
 	@echo "  generate   Generate code (e.g., templ files)."
 	@echo "  test       Run Go tests."
 	@echo "  fmt        Format Go and templ code."
-	@echo "  lint       Run golangci-lint (requires installation)."
 	@echo "  tidy       Tidy Go module files."
+	@echo "  lint       Run golangci-lint (requires installation)."
+
+setup:
+	@echo "Running setup script..."
+	@./scripts/setup.sh
 
 build: generate
 	@echo "Building $(BINARY_NAME) into $(OUTPUT_DIR)/..."
@@ -49,4 +54,4 @@ tidy:
 
 lint:
 	@echo "Linting code... (requires golangci-lint)"
-	@golangci-lint run 
+	@golangci-lint run
diff --git a/README.md b/README.md
@@ -2,12 +2,93 @@
 
 This repository contains the source code for the Agent Browser.
 
-## Project Setup (Golang)
+## Project Structure
 
-This project is being set up using Golang and the `fx` framework.
+This project uses Go modules and follows a standard Go project layout:
 
-Refer to `.cursor/TASK_LIST.md` for the setup tasks.
+* `/cmd`: Main application entry points.
+* `/internal`: Private application code (not intended for import by other projects).
+  * `/app`: Core application setup and Fx module wiring.
+  * `/config`: Configuration loading and management.
+  * `/log`: Logging setup and utilities.
+  * `/mcp`: MCP abstraction and utilities.
+  * `/services`: Core business logic implementations.
+  * `/sync`: Sync daemon. (PLACEHOLDER)
+  * `/updater`: Software update logic. (PLACEHOLDER)
+  * `/web`: Web server related code.
+    * `/handlers`: HTTP request handlers.
+    * `/templates`: HTML templates (using `templ`).
+* `/pkg`: Library code intended for external use (currently N/A).
+* `/scripts`: Scripts in Bash, Python, etc., for complex actions in this repository.
+* `/out`: Compiled binaries (ignored by git).
 
 ## Getting Started
 
-ToDo
+### Prerequisites
+
+1. **Go:** Ensure you have Go installed (version 1.21 or later recommended). You can download it from [https://go.dev/dl/](https://go.dev/dl/).
+2. **Bash:** The setup script uses `bash` specific features.
+3. **Environment Setup:** The setup script (`make setup`) will check if your `$GOPATH/bin` directory is in your `PATH` and provide instructions if it isn't. This directory is needed to run Go tools installed via `go install`.
+
+    You can manually verify by running `go env GOPATH` and checking your shell's configuration (e.g., `.zshrc`, `.bashrc`). Example:
+    ```bash
+    export GOPATH="$(go env GOPATH)" # Or explicitly set, e.g., export GOPATH="$HOME/go"
+    export PATH="$PATH:$GOPATH/bin"
+    ```
+
+### Installation & Setup
+
+1. **Clone the repository:**
+
+    ```bash
+    git clone https://github.com/co-browser/agent-browser.git
+    cd agent-browser
+    ```
+
+2. **Install Tools & Dependencies:** Run the setup command. This executes `scripts/setup.sh` which installs required Go tools (`templ`, `golangci-lint`) and checks your `PATH`.
+
+    ```bash
+    make setup
+    ```
+
+3. **Download Go Modules:**
+
+    ```bash
+    make tidy
+    ```
+
+### Running the Application
+
+1. **Build and Run:**
+
+    ```bash
+    make run
+    ```
+
+    This will compile the application into the `out/` directory and start the server (defaulting to `localhost:8080`).
+
+2. **Access the UI (Placeholder):** Open your browser to `http://localhost:8080/ui`.
+
+## Development
+
+### Common Makefile Targets
+
+* `make setup`: Runs `scripts/setup.sh` to install/update necessary development tools (`templ`, `golangci-lint`) and check `PATH`.
+* `make build`: Compile the application binary into `out/agent-browser`.
+* `make run`: Build and run the application.
+* `make generate`: Generate Go code from `.templ` files.
+* `make test`: Run Go tests.
+* `make fmt`: Format Go code (`gofmt`) and `.templ` files (`templ fmt`).
+* `make tidy`: Tidy `go.mod` and `go.sum` files.
+* `make lint`: Run the Go linter (`golangci-lint`).
+* `make help`: Show all available targets.
+
+## Continuous Integration
+
+This project uses GitHub Actions for Continuous Integration (CI) and release automation. The workflows are defined in the `.github/workflows/` directory.
+
+*   **Go CI (`go.yaml`):** This workflow runs on pushes and pull requests to the `main` and `develop` branches. It checks out the code, sets up Go, runs `make setup`, `make tidy`, formatting checks (`make fmt`), linting (`make lint`), tests (`make test`) and builds the project (`make build`) to ensure Go code quality and stability.
+
+*   **MegaLinter (`mega-linter.yaml`):** This workflow runs on pushes and pull requests to the `main` branch. It utilizes [MegaLinter](https://megalinter.io/) to analyze the entire codebase using a wide range of linters for various languages and formats (including Go, YAML, Markdown, Shell scripts, etc.). This helps maintain consistent coding standards and identify potential issues across the whole project. Reports are uploaded as artifacts.
+
+*   **Release (`release.yaml`):** This workflow runs only on pushes to the `main` branch. It uses [semantic-release](https://github.com/semantic-release/semantic-release) to automate version management and package publishing. Based on conventional commit messages, it determines the next version number, generates release notes, and creates a Git tag and GitHub release.
diff --git a/internal/app/app_test.go b/internal/app/app_test.go
@@ -0,0 +1,15 @@
+package app_test
+
+import (
+	"testing"
+)
+
+// TestAppDummy is a placeholder test.
+// It verifies that the test suite runs.
+// TODO: Replace with actual application tests.
+func TestAppDummy(t *testing.T) {
+	// Keep t parameter used
+	_ = t
+	// This test doesn't do anything yet, but confirms tests can be discovered and run.
+	// t.Log("Dummy application test executed successfully.")
+}
diff --git a/internal/services/services.go b/internal/services/services.go
@@ -0,0 +1 @@
+package services
diff --git a/internal/web/templates/index.templ b/internal/web/templates/index.templ
@@ -14,4 +14,4 @@ templ IndexPage() {
 			<!-- Add more content here -->
 		</body>
 	</html>
-}
+}
diff --git a/scripts/setup.sh b/scripts/setup.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
+cd "$SCRIPT_DIR"
+
+# Function to print messages
+log() {
+	echo "$(date '+%Y-%m-%d %H:%M:%S') - $1"
+}
+
+# Function to print success messages (green)
+echo_success() {
+    printf "\033[0;32m✓ %s\033[0m\n" "$1"
+}
+
+# Function to print warning messages (yellow)
+echo_warn() {
+    printf "\033[0;33mWARN: %s\033[0m\n" "$1"
+}
+
+log "Starting setup..."
+
+log "Installing templ..."
+go install github.com/a-h/templ/cmd/templ@latest
+
+log "Installing golangci-lint..."
+go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
+
+log "Checking PATH environment variable..."
+
+# Determine GOPATH/bin
+GOPATH_BIN=$(go env GOPATH)/bin
+
+# Check if GOPATH/bin could be determined
+if [ -z "$GOPATH_BIN" ] || [ "$GOPATH_BIN" = "/bin" ]; then
+    echo_warn "Could not determine GOPATH/bin. Please ensure GOPATH is set correctly."
+else
+    # Use awk to check if GOPATH_BIN is a distinct component in PATH
+    if echo "$PATH" | awk -v path_to_check="$GOPATH_BIN" 'BEGIN { FS=":"; found=0 } { for(i=1; i<=NF; i++) if ($i == path_to_check) { found=1; exit 0 } } END { exit !found }'; then
+        echo_success "$GOPATH_BIN appears to be in your PATH."
+    else
+        echo_warn "$GOPATH_BIN does not appear to be in your PATH."
+        echo "         Please add it to your shell configuration (e.g., .zshrc, .bashrc):"
+        echo "         export PATH=\"$PATH:$GOPATH_BIN\""
+    fi
+fi
+
+# Use printf for the final success message too
+printf "\033[0;32m✓ %s\033[0m\n" "Setup complete." 

-Original file line number
+Diff line change
 			<!-- Add more content here -->
 		</body>
 	</html>
 -}
 +}