migrate to SQLite and prepare for MCP deployment

Switch from PostgreSQL to SQLite (modernc.org/sqlite, pure Go) for
simpler deployment on the MCP platform. Fix URL normalization to
preserve query parameters so sites like YouTube deduplicate correctly.
Add Dockerfile, Makefile, and MCP service definition. Add pg2sqlite
migration tool. Support $PORT env var for MCP port assignment.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-03-27 16:18:37 -07:00
parent 25e38814a2
commit 0fa85cb300
14 changed files with 363 additions and 126 deletions

43
CLAUDE.md Normal file
View File

@@ -0,0 +1,43 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## What is kls
A URL shortener web service. Users submit a URL, get back a 5-character short code. Visiting `/<code>` redirects to the original URL. Admin routes (POST, /list) are protected with HTTP Basic Auth.
## Build and Run
```bash
go build -o kls .
./kls -f /path/to/kls.conf
```
No Makefile, no tests. The binary is `.gitignore`d.
## Configuration
Uses `goutils/config` to load a key=value config file (default `~/.config/kls/kls.conf`). Required keys:
- `DB_PASSWORD`, `DB_HOST` — no defaults
- `HTTP_USER`, `HTTP_PASS` — Basic Auth credentials
- `HTTP_ADDR` — bind address
Optional (have defaults): `DB_ENGINE` (postgres), `DB_NAME` (kls), `DB_USER` (kls), `DB_PORT` (5432), `HTTP_PORT` (8000).
## Architecture
- **`main.go`** — entry point: loads config, connects to DB, starts HTTP server.
- **`handler.go`** — HTTP routing and handlers on the `server` struct. Implements `ServeHTTP` directly (no router library). GET requests matching a valid short code bypass auth and redirect; everything else requires Basic Auth. Templates are embedded via `//go:embed`.
- **`links/`** — core domain package:
- `url.go``URL` model, CRUD operations (Store, Lookup, StoreURL, RetrieveURL, FetchAll), URL normalization (strips query/fragment by default), and cleaning logic. Uses squirrel for query building with PostgreSQL dollar placeholders.
- `db.go` — PostgreSQL connection setup via pgx/v4 pool.
- `alphabet.go` — short code generation: 5 random characters from an unambiguous alphabet (`ABCDEFGHJKMNPQRSTUVWXYZ23456789`, excludes 0/O/1/I/L). `ValidShortCode` regex is used for routing.
- **`schema.sql`** — single `urls` table with `id` (UUID), `url`, `nurl` (normalized), `short` (unique), `created_at`.
- **`templates/`** — Go HTML templates (`index.tpl` for submit form, `list.tpl` for listing all URLs).
## Key behaviors
- **Deduplication**: `StoreURL` checks for an existing normalized URL before creating a new entry.
- **URL cleaning**: By default, query strings are stripped. The "rawp" form checkbox preserves the original query string.
- **No router**: `server.ServeHTTP` handles all dispatch — check there when adding routes.