diff --git a/CLAUDE.md b/CLAUDE.md index b7f254e..e136dd7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -kafka is a privacy-respecting metasearch engine written in Go. It provides a SearXNG-compatible `/search` API and an HTML frontend (HTMX + Go templates). 9 engines are implemented natively in Go; unlisted engines can be proxied to an upstream metasearch instance. Responses from multiple engines are merged into a single JSON/CSV/RSS/HTML response. +samsa is a privacy-respecting metasearch engine written in Go. It provides a SearXNG-compatible `/search` API and an HTML frontend (HTMX + Go templates). 9 engines are implemented natively in Go; unlisted engines can be proxied to an upstream metasearch instance. Responses from multiple engines are merged into a single JSON/CSV/RSS/HTML response. ## Build & Run Commands @@ -22,7 +22,7 @@ go test -run TestWikipedia ./internal/engines/ go test -v ./internal/engines/ # Run the server (requires config.toml) -go run ./cmd/kafka -config config.toml +go run ./cmd/samsa -config config.toml ``` There is no Makefile. There is no linter configured. @@ -43,7 +43,7 @@ There is no Makefile. There is no linter configured. - `internal/cache` — Valkey/Redis-backed cache with SHA-256 cache keys. No-op if unconfigured. - `internal/middleware` — Three rate limiters (per-IP sliding window, burst+sustained, global) and CORS. All disabled by default. - `internal/views` — HTML templates and static files embedded via `//go:embed`. Renders full pages or HTMX fragments. Templates: `base.html`, `index.html`, `results.html`, `results_inner.html`, `result_item.html`. -- `cmd/kafka` — Entry point. Loads TOML config, seeds env vars for engine code, wires up middleware chain, starts HTTP server. +- `cmd/samsa` — Entry point. Loads TOML config, seeds env vars for engine code, wires up middleware chain, starts HTTP server. **Engine interface** (`internal/engines/engine.go`): ```go @@ -66,7 +66,7 @@ Config is loaded from `config.toml` (see `config.example.toml`). All fields can ## Conventions -- Module path: `github.com/metamorphosis-dev/kafka` +- Module path: `github.com/metamorphosis-dev/samsa` - Tests use shared mock helpers in `internal/engines/http_mock_test.go` (`roundTripperFunc`, `httpResponse`) - Engine implementations are single files under `internal/engines/` (e.g., `wikipedia.go`, `duckduckgo.go`) - Response merging de-duplicates by `engine|title|url` key; suggestions/corrections are merged as sets diff --git a/README.md b/README.md index 25c1c29..f7fd2d4 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# kafka +# samsa A privacy-respecting, open metasearch engine written in Go. SearXNG-compatible API with an HTML frontend, designed to be fast, lightweight, and deployable anywhere. @@ -12,7 +12,7 @@ A privacy-respecting, open metasearch engine written in Go. SearXNG-compatible A - **Valkey cache** — optional Redis-compatible caching with configurable TTL - **Rate limiting** — three layers: per-IP, burst, and global (all disabled by default) - **CORS** — configurable origins for browser-based clients -- **OpenSearch** — browsers can add kafka as a search engine from the address bar +- **OpenSearch** — browsers can add samsa as a search engine from the address bar - **Graceful degradation** — individual engine failures don't kill the whole search - **Docker** — multi-stage build, ~20MB runtime image - **NixOS** — native NixOS module with systemd service @@ -23,9 +23,9 @@ A privacy-respecting, open metasearch engine written in Go. SearXNG-compatible A ```bash git clone https://git.ashisgreat.xyz/penal-colony/gosearch.git -cd kafka -go build ./cmd/kafka -./kafka -config config.toml +cd samsa +go build ./cmd/samsa +./samsa -config config.toml ``` ### Docker Compose @@ -41,28 +41,28 @@ docker compose up -d Add to your flake inputs: ```nix -inputs.kafka.url = "git+https://git.ashisgreat.xyz/penal-colony/gosearch.git"; +inputs.samsa.url = "git+https://git.ashisgreat.xyz/penal-colony/gosearch.git"; ``` Enable in your configuration: ```nix -imports = [ inputs.kafka.nixosModules.default ]; +imports = [ inputs.samsa.nixosModules.default ]; -services.kafka = { +services.samsa = { enable = true; openFirewall = true; baseUrl = "https://search.example.com"; - # config = "/etc/kafka/config.toml"; # default + # config = "/etc/samsa/config.toml"; # default }; ``` Write your config: ```bash -sudo mkdir -p /etc/kafka -sudo cp config.example.toml /etc/kafka/config.toml -sudo $EDITOR /etc/kafka/config.toml +sudo mkdir -p /etc/samsa +sudo cp config.example.toml /etc/samsa/config.toml +sudo $EDITOR /etc/samsa/config.toml ``` Deploy: @@ -76,7 +76,7 @@ sudo nixos-rebuild switch --flake .# ```bash nix develop go test ./... -go run ./cmd/kafka -config config.toml +go run ./cmd/samsa -config config.toml ``` ## Endpoints diff --git a/cmd/kafka/main.go b/cmd/samsa/main.go similarity index 89% rename from cmd/kafka/main.go rename to cmd/samsa/main.go index 68fa1dd..8e09667 100644 --- a/cmd/kafka/main.go +++ b/cmd/samsa/main.go @@ -1,4 +1,4 @@ -// kafka — a privacy-respecting metasearch engine +// samsa — a privacy-respecting metasearch engine // Copyright (C) 2026-present metamorphosis-dev // // This program is free software: you can redistribute it and/or modify @@ -25,13 +25,13 @@ import ( "net/http" "os" - "github.com/metamorphosis-dev/kafka/internal/autocomplete" - "github.com/metamorphosis-dev/kafka/internal/cache" - "github.com/metamorphosis-dev/kafka/internal/config" - "github.com/metamorphosis-dev/kafka/internal/httpapi" - "github.com/metamorphosis-dev/kafka/internal/middleware" - "github.com/metamorphosis-dev/kafka/internal/search" - "github.com/metamorphosis-dev/kafka/internal/views" + "github.com/metamorphosis-dev/samsa/internal/autocomplete" + "github.com/metamorphosis-dev/samsa/internal/cache" + "github.com/metamorphosis-dev/samsa/internal/config" + "github.com/metamorphosis-dev/samsa/internal/httpapi" + "github.com/metamorphosis-dev/samsa/internal/middleware" + "github.com/metamorphosis-dev/samsa/internal/search" + "github.com/metamorphosis-dev/samsa/internal/views" ) func main() { @@ -127,7 +127,7 @@ func main() { }, logger)(handler) addr := fmt.Sprintf(":%d", cfg.Server.Port) - logger.Info("kafka starting", + logger.Info("samsa starting", "addr", addr, "cache", searchCache.Enabled(), "rate_limit", cfg.RateLimit.Requests > 0, diff --git a/config.example.toml b/config.example.toml index 042bb63..10af1b2 100644 --- a/config.example.toml +++ b/config.example.toml @@ -1,4 +1,4 @@ -# kafka configuration +# samsa configuration # Copy to config.toml and adjust as needed. # Environment variables are used as fallbacks when a config field is empty/unset. @@ -10,13 +10,13 @@ port = 8080 http_timeout = "10s" # Public base URL for OpenSearch XML (env: BASE_URL) -# Set this so browsers can add kafka as a search engine. +# Set this so browsers can add samsa as a search engine. # Example: "https://search.example.com" base_url = "" # Link to the source code (shown in footer as "Source" link) -# Defaults to the upstream kafka repo if not set. -# Example: "https://git.example.com/my-kafka-fork" +# Defaults to the upstream samsa repo if not set. +# Example: "https://git.example.com/my-samsa-fork" source_url = "" [upstream] diff --git a/docs/superpowers/plans/2026-03-22-brave-search-frontend-redesign.md b/docs/superpowers/plans/2026-03-22-brave-search-frontend-redesign.md index 28b98a1..5b6ad9b 100644 --- a/docs/superpowers/plans/2026-03-22-brave-search-frontend-redesign.md +++ b/docs/superpowers/plans/2026-03-22-brave-search-frontend-redesign.md @@ -2,7 +2,7 @@ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. -**Goal:** Redesign the kafka frontend to match Brave Search's layout: three-column results page, category tiles on homepage, and a hybrid preferences system with full-page `/preferences` route. +**Goal:** Redesign the samsa frontend to match Brave Search's layout: three-column results page, category tiles on homepage, and a hybrid preferences system with full-page `/preferences` route. **Architecture:** CSS Grid for page-level layouts (three-column results, two-column preferences). JavaScript popover for quick settings (theme + engines only). Server-rendered full preferences page with localStorage persistence. Category tiles are static links with category query params. @@ -14,7 +14,7 @@ | File | Responsibility | |------|----------------| -| `internal/views/static/css/kafka.css` | Add layout grids, category tiles, sidebar styles, mobile breakpoints | +| `internal/views/static/css/samsa.css` | Add layout grids, category tiles, sidebar styles, mobile breakpoints | | `internal/views/templates/index.html` | Add category tiles below search box | | `internal/views/templates/results.html` | Add left sidebar, restructure for three-column grid | | `internal/views/templates/preferences.html` | **New** — full preferences page with nav | @@ -30,11 +30,11 @@ ### Task 1: Add CSS Grid Layouts and Breakpoints **Files:** -- Modify: `internal/views/static/css/kafka.css` +- Modify: `internal/views/static/css/samsa.css` - [ ] **Step 1: Add three-column results layout CSS** -Append to end of `kafka.css`, before the `@media print` block: +Append to end of `samsa.css`, before the `@media print` block: ```css /* ============================================================ @@ -364,7 +364,7 @@ Note: CSS is embedded as static files and not processed by the Go compiler. CSS - [ ] **Step 7: Commit** ```bash -git add internal/views/static/css/kafka.css +git add internal/views/static/css/samsa.css git commit -m "feat(frontend): add CSS layout framework for three-column results and preferences page" ``` @@ -895,7 +895,7 @@ git commit -m "feat(frontend): add category tiles to homepage" - [ ] **Step 2: Add preferences section CSS styles** -Append to `kafka.css`: +Append to `samsa.css`: ```css /* ============================================================ @@ -1010,7 +1010,7 @@ func RenderPreferences(w http.ResponseWriter, sourceURL string) error { - [ ] **Step 4: Commit** ```bash -git add internal/views/templates/preferences.html internal/views/static/css/kafka.css internal/views/views.go +git add internal/views/templates/preferences.html internal/views/static/css/samsa.css internal/views/views.go git commit -m "feat(frontend): add preferences page template and styles" ``` @@ -1020,7 +1020,7 @@ git commit -m "feat(frontend): add preferences page template and styles" **Files:** - Modify: `internal/httpapi/handlers.go` -- Modify: `cmd/kafka/main.go` +- Modify: `cmd/samsa/main.go` - [ ] **Step 1: Add GET and POST handlers for /preferences** @@ -1053,7 +1053,7 @@ func (h *Handler) PreferencesPOST(w http.ResponseWriter, r *http.Request) { - [ ] **Step 2: Register the route in main** -Find where routes are registered (likely in `cmd/kafka/main.go`) and add: +Find where routes are registered (likely in `cmd/samsa/main.go`) and add: ```go mux.HandleFunc("GET /preferences", handler.Preferences) @@ -1068,7 +1068,7 @@ Expected: No errors - [ ] **Step 4: Commit** ```bash -git add internal/httpapi/handlers.go cmd/kafka/main.go +git add internal/httpapi/handlers.go cmd/samsa/main.go git commit -m "feat: add GET and POST /preferences route" ``` @@ -1192,7 +1192,7 @@ git commit -m "fix(frontend): add HTMX filter submission" ### Task 8: Final Mobile Responsiveness Audit **Files:** -- Review: `internal/views/static/css/kafka.css` +- Review: `internal/views/static/css/samsa.css` - [ ] **Step 1: Test all breakpoints manually** @@ -1201,7 +1201,7 @@ git commit -m "fix(frontend): add HTMX filter submission" - [ ] **Step 3: Commit any fixes** ```bash -git add internal/views/static/css/kafka.css +git add internal/views/static/css/samsa.css git commit -m "fix(frontend): improve mobile responsiveness" ``` @@ -1211,7 +1211,7 @@ git commit -m "fix(frontend): improve mobile responsiveness" | Phase | Task | Files | |-------|------|-------| -| 1 | CSS Layout Framework | `kafka.css` | +| 1 | CSS Layout Framework | `samsa.css` | | 2 | Results Three-Column | `results.html`, `views.go` | | 3 | Homepage Tiles | `index.html` | | 4 | Preferences Page | `preferences.html` (new), `handlers.go`, `settings.js` | diff --git a/docs/superpowers/plans/2026-03-22-settings-ui.md b/docs/superpowers/plans/2026-03-22-settings-ui.md index cf34df5..8b68536 100644 --- a/docs/superpowers/plans/2026-03-22-settings-ui.md +++ b/docs/superpowers/plans/2026-03-22-settings-ui.md @@ -4,9 +4,9 @@ **Goal:** A preferences popover panel (top-right on desktop, bottom sheet on mobile) that lets users set theme, enabled engines, safe search, and default format. All changes auto-save to `localStorage` and apply immediately to the DOM. -**Architecture:** Pure client-side JS + CSS added alongside existing templates. No Go changes. Settings persist via `localStorage` key `kafka_prefs`. Theme applies via `data-theme` attribute on ``. +**Architecture:** Pure client-side JS + CSS added alongside existing templates. No Go changes. Settings persist via `localStorage` key `samsa_prefs`. Theme applies via `data-theme` attribute on ``. -**Tech Stack:** Vanilla JS (no framework), existing `kafka.css` custom properties, HTMX for search. +**Tech Stack:** Vanilla JS (no framework), existing `samsa.css` custom properties, HTMX for search. --- @@ -15,7 +15,7 @@ | Action | File | |--------|------| | Create | `internal/views/static/js/settings.js` | -| Modify | `internal/views/static/css/kafka.css` | +| Modify | `internal/views/static/css/samsa.css` | | Modify | `internal/views/templates/base.html` | | Modify | `internal/views/templates/index.html` | | Modify | `internal/views/templates/results.html` | @@ -28,11 +28,11 @@ ## Task 1: CSS — Popover, toggles, bottom sheet **Files:** -- Modify: `internal/views/static/css/kafka.css` +- Modify: `internal/views/static/css/samsa.css` - [ ] **Step 1: Add CSS for popover, triggers, toggles, bottom sheet** -Append the following to `kafka.css`: +Append the following to `samsa.css`: ```css /* ============================================ @@ -305,7 +305,7 @@ Expected: all pass - [ ] **Step 3: Commit** ```bash -git add internal/views/static/css/kafka.css +git add internal/views/static/css/samsa.css git commit -m "feat(settings): add popover, toggle, and bottom-sheet CSS" ``` @@ -335,7 +335,7 @@ var DEFAULT_PREFS = { format: 'html' }; -var STORAGE_KEY = 'kafka_prefs'; +var STORAGE_KEY = 'samsa_prefs'; // ── Persistence ────────────────────────────────────────────────────────────── @@ -619,7 +619,7 @@ In `base.html`, update the `` to: {{if .ShowHeader}}
- kafka + samsa @@ -633,7 +633,7 @@ In `base.html`, update the `` to: {{template "content" .}}