2025-10-21 10:11:48+04:00

CLAUDE.md

@@ -0,0 +1,154 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+LinkBeam is a static site generator for creating personal link-in-bio pages (similar to Linktree). It reads a YAML configuration file containing user profile information, links, and social media, then generates a themed HTML page using Go templates.
+
+## CI/CD Pipeline
+
+The project uses Gitea Actions for continuous integration and deployment.
+
+### Workflows
+
+1. **CI Pipeline** (`.gitea/workflows/ci.yml`):
+   - Runs on push to main/develop and pull requests
+   - **Lint**: golangci-lint, go fmt, go vet
+   - **Test**: Run tests with race detection and coverage
+   - **Build**: Multi-platform builds (Linux, Windows, macOS) for amd64, 386, arm64, armv7
+   - **Docker**: Build multi-arch Docker images
+
+2. **Docker Publish** (`.gitea/workflows/docker-publish.yml`):
+   - Triggered on version tags (v*)
+   - Builds and pushes Docker images to container registry
+   - Multi-architecture: linux/amd64, linux/arm64, linux/arm/v7
+
+3. **Release** (`.gitea/workflows/release.yml`):
+   - Triggered on semver tags (v*.*.*)
+   - Creates GitHub/Gitea releases with binaries for all platforms
+   - Generates SHA256 checksums for verification
+
+### Local Testing
+
+```bash
+# Check version
+./linkbeam -v
+# or: ./linkbeam --version
+
+# Test Docker build
+docker build -t linkbeam:test .
+
+# Run Docker container
+docker run -v $(pwd)/config.yaml:/app/config/config.yaml \
+           -v $(pwd)/dist:/app/dist \
+           linkbeam:test
+
+# Test with docker-compose
+docker-compose up
+```
+
+## Development Commands
+
+### Pre-commit Setup
+
+This project uses pre-commit hooks for code quality. First-time setup:
+
+```bash
+# Install pre-commit hooks
+make install-hooks
+# or: pre-commit install
+
+# Run all hooks manually
+make pre-commit
+# or: pre-commit run --all-files
+```
+
+The hooks automatically run on commit and check: `go fmt`, `goimports`, `go vet`, `golangci-lint`, `go test`, `go mod tidy`, YAML syntax, and more.
+
+### Building and Running
+```bash
+# Build binary (outputs to dist/linkbeam)
+make build
+# or: go build -o dist/linkbeam cmd/linkbeam/main.go
+
+# Run with example config
+make run-example
+# or: go run cmd/linkbeam/main.go --config internal/config/testdata/config.yaml
+
+# Run with custom config (long flags)
+./linkbeam --config config.yaml --template templates/base.html --output dist/index.html
+
+# Run with custom config (short flags)
+./linkbeam -c config.yaml -t templates/base.html -o dist/index.html
+
+# Run all tests
+make test
+# or: go test -v ./...
+
+# Run tests for a specific package
+go test ./internal/config
+go test ./internal/generator
+
+# Run a single test function
+go test -v -run TestLoad ./internal/config
+
+# Clean build artifacts
+make clean
+```
+
+### CLI Options
+- `-c, --config`: Path to config YAML file (default: "config.yaml")
+- `-t, --template`: Path to HTML template (default: "templates/base.html")
+- `-o, --output`: Path to output HTML file (default: "dist/index.html")
+- `-v, --version`: Print version information
+
+### Output
+The `dist/` directory contains both build artifacts and generated site:
+- `dist/linkbeam` - Compiled binary
+- `dist/index.html` - Main HTML page
+- `dist/themes/` - Copied CSS theme files
+
+## Architecture
+
+### Two-Layer Structure
+
+1. **Config Layer** (`internal/config/`):
+   - Loads and validates YAML configuration files
+   - Defines data structures: `Config`, `Link`, `Social`
+   - Validates theme (must be "light" or "dark") and required fields (name cannot be empty)
+   - Config validation happens automatically during `config.Load()`
+
+2. **Generator Layer** (`internal/generator/`):
+   - **HTML Generation**: Orchestrates template rendering using Go's `html/template`
+     - `GenerateSite(cfg, templatePath, outPath)` - Creates HTML from templates
+   - **Asset Management**: Copies CSS themes and static files to output directory
+     - `CopyAssets(distDir, themeDirs...)` - Copies theme files to dist/themes/
+   - **Text Rendering**: Plain-text representation for debugging
+     - `RenderUserPage(cfg)` - Returns text-based preview of the page
+
+### Configuration Format
+
+The config YAML structure in `internal/config/testdata/config.yaml`:
+- `name`: User's display name (required)
+- `bio`: Short biography text
+- `avatar`: Path to avatar image
+- `theme`: "light" or "dark" (validated)
+- `links[]`: Array of link objects with `title`, `url`, `icon`
+- `socials[]`: Array of social media links with `platform`, `url`, `icon`
+
+### Templates
+
+Templates in `templates/` use Go template syntax:
+- `base.html`: Main page template with theme support (`data-theme="{{ .Theme }}"`)
+- Template receives the entire `Config` struct as data
+- Access config fields with `{{ .Name }}`, `{{ .Bio }}`, etc.
+- Iterate over links with `{{- range .Links }}`
+
+### Testing Strategy
+
+- Tests use table-driven patterns and dependency injection
+- `cmd/linkbeam/main_test.go`: Mocks the config loader and captures stdout
+- Config tests validate YAML parsing and business rules
+- Generator tests verify file creation and template execution
+- All tests use the testdata in `internal/config/testdata/config.yaml`