golinks 1.0.0__tar.gz

golinks-1.0.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+.eggs/
+*.manifest
+*.spec
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# Package managers
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Distribution / packaging
+.Python
+develop-eggs/
+downloads/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.whl
+.env

golinks-1.0.0/.python-version

@@ -0,0 +1 @@
+3.11

golinks-1.0.0/CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+Use uv to run Python code:
+```bash
+# Run the server
+uv run golinks
+
+# Run with custom config
+uv run golinks --config /path/to/config.json
+
+# Run with custom port
+uv run golinks --port 9000
+
+# Run any Python command
+uv run python <script.py>
+```
+
+## Linting
+
+```bash
+# Run linter
+uv run ruff check .
+
+# Fix linting issues
+uv run ruff check --fix .
+
+# Format code
+uv run ruff format .
+```
+
+## Architecture
+
+### Core Components
+
+**HTTP Server** (`src/server.py`):
+- Uses Python's built-in `http.server` module with custom `GoLinksHandler`
+- Handles redirects based on path matching against configured shortcuts
+- Hot-reloads configuration on each request (no restart needed)
+- Serves web interface at root path showing all available links
+
+**Configuration** (`src/models.py`):
+- Pydantic models for type-safe configuration handling
+- Supports simple string URLs or template objects with Jinja2 templating
+- `LinkTemplate` allows for parameterized URLs with defaults
+
+**Templates** (`src/templates/`):
+- Jinja2 templates for the web interface
+- `base.html`: Base template with common styles
+- `links.html`: Shows all configured shortcuts
+- `error.html`: Friendly 404 page for unknown shortcuts
+
+### Key Design Patterns
+
+1. **Hot-reload Configuration**: Config is loaded fresh on each request from JSON file
+2. **Template URLs**: Links can use Jinja2 templates with query parameters as variables
+3. **Query Parameter Preservation**: Unmatched query params are passed through to destination
+4. **No External Dependencies**: Uses Python stdlib where possible (except Jinja2, Pydantic)
+
+### Configuration Format
+
+Simple redirects:
+```json
+{
+  "github": "https://github.com"
+}
+```
+
+Template redirects with defaults:
+```json
+{
+  "search": {
+    "template_url": "https://www.google.com/search?q={{q|default('python')}}",
+    "defaults": {
+      "q": "python"
+    }
+  }
+}
+```

golinks-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

golinks-1.0.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: golinks
+Version: 1.0.0
+Summary: A local go links redirect service for URL shortcuts
+Project-URL: Homepage, https://github.com/yourusername/golinks
+Project-URL: Repository, https://github.com/yourusername/golinks.git
+Project-URL: Issues, https://github.com/yourusername/golinks/issues
+Author-email: Haran Rajkumar <haranrajkumar97@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: golinks,redirect,shortcuts,url-shortener
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pydantic>=2.11.9
+Description-Content-Type: text/markdown
+
+# Golinks
+
+A simple local HTTP redirect service that turns short URLs like `go/github` into full URLs.
+
+## Installation
+
+### Install manually
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/golinks.git
+cd golinks
+
+# Run the install script
+./install
+
+# Edit the config
+vim ~/.config/golinks/config.json
+```
+
+## How it works
+
+The `./install` script automates the entire setup:
+1. Installs the Python package using uv
+2. Adds `127.0.0.1 go` to your `/etc/hosts` file (with sudo permission)
+3. Sets up port forwarding from port 80 to 8888 using pfctl (macOS) or iptables (Linux), so you can use `go/shortcut` instead of `go:8888/shortcut`
+4. Sets up a LaunchAgent (macOS) or systemd service (Linux) to run the server at startup
+5. Starts the golinks server immediately on port 8888
+
+Once installed, golinks runs a lightweight HTTP server that reads shortcuts from a JSON config file at `~/.golinks/config.json` and redirects `http://go/shortcut` to the configured destination URL. The config file is hot-reloaded, so you can add new shortcuts without restarting the server.

golinks-1.0.0/README.md

@@ -0,0 +1,30 @@
+# Golinks
+
+A simple local HTTP redirect service that turns short URLs like `go/github` into full URLs.
+
+## Installation
+
+### Install manually
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/golinks.git
+cd golinks
+
+# Run the install script
+./install
+
+# Edit the config
+vim ~/.config/golinks/config.json
+```
+
+## How it works
+
+The `./install` script automates the entire setup:
+1. Installs the Python package using uv
+2. Adds `127.0.0.1 go` to your `/etc/hosts` file (with sudo permission)
+3. Sets up port forwarding from port 80 to 8888 using pfctl (macOS) or iptables (Linux), so you can use `go/shortcut` instead of `go:8888/shortcut`
+4. Sets up a LaunchAgent (macOS) or systemd service (Linux) to run the server at startup
+5. Starts the golinks server immediately on port 8888
+
+Once installed, golinks runs a lightweight HTTP server that reads shortcuts from a JSON config file at `~/.golinks/config.json` and redirects `http://go/shortcut` to the configured destination URL. The config file is hot-reloaded, so you can add new shortcuts without restarting the server.

golinks-1.0.0/config.json

@@ -0,0 +1,7 @@
+{
+  "github": "https://github.com",
+  "mail": "https://gmail.com",
+  "calendar": "https://calendar.google.com",
+  "docs": "https://docs.google.com",
+  "drive": "https://drive.google.com"
+}

golinks-1.0.0/install.sh

@@ -0,0 +1,295 @@
+#!/bin/bash
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+echo_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+echo_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+echo_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Check if already installed
+check_installation() {
+    if command -v golinks &> /dev/null; then
+        if uv tool list 2>/dev/null | grep -q golinks; then
+            echo_warning "golinks is already installed"
+            return 0
+        fi
+    fi
+    return 1
+}
+
+# Install uv if missing
+install_uv() {
+    if ! command -v uv &> /dev/null; then
+        echo_info "Installing uv package manager..."
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+
+        # Source shell config to get uv in PATH
+        if [ -f "$HOME/.bashrc" ]; then
+            source "$HOME/.bashrc"
+        elif [ -f "$HOME/.zshrc" ]; then
+            source "$HOME/.zshrc"
+        fi
+
+        # Add to current shell session
+        export PATH="$HOME/.cargo/bin:$PATH"
+
+        if ! command -v uv &> /dev/null; then
+            echo_error "Failed to install uv. Please install manually."
+            exit 1
+        fi
+        echo_success "uv installed successfully"
+    else
+        echo_info "uv is already installed"
+    fi
+}
+
+# Install golinks tool
+install_golinks() {
+    echo_info "Installing golinks..."
+
+    # Install from the current directory if we're in the repo
+    if [ -f "pyproject.toml" ]; then
+        uv tool install .
+    else
+        # Install from PyPI or git
+        uv tool install golinks
+    fi
+
+    if [ $? -eq 0 ]; then
+        echo_success "golinks installed successfully"
+    else
+        echo_error "Failed to install golinks"
+        exit 1
+    fi
+}
+
+# Create configuration directory and file
+setup_config() {
+    CONFIG_DIR="$HOME/.config/golinks"
+    CONFIG_FILE="$CONFIG_DIR/config.json"
+
+    echo_info "Setting up configuration..."
+
+    # Create config directory
+    mkdir -p "$CONFIG_DIR"
+
+    # Create config file if it doesn't exist
+    if [ ! -f "$CONFIG_FILE" ]; then
+        cat > "$CONFIG_FILE" <<EOF
+{
+  "github": "https://github.com",
+  "mail": "https://gmail.com",
+  "calendar": "https://calendar.google.com",
+  "prs": {
+    "template_url": "https://github.com/MithraAI/{1}/pull/{2}",
+    "defaults": {
+      "1": "istari"
+    }
+  },
+  "issue": {
+    "template_url": "https://github.com/{1}/{2}/issues/{3}",
+    "defaults": {
+      "1": "anthropics",
+      "2": "claude-code"
+    }
+  }
+}
+EOF
+        echo_success "Configuration file created at $CONFIG_FILE"
+    else
+        echo_info "Configuration file already exists"
+    fi
+}
+
+# Add entry to /etc/hosts
+setup_hosts() {
+    echo_info "Configuring /etc/hosts..."
+
+    # Check if entry already exists
+    if grep -q "127.0.0.1[[:space:]]*go$" /etc/hosts 2>/dev/null; then
+        echo_info "/etc/hosts already configured"
+    else
+        echo_info "Adding 'go' to /etc/hosts (requires sudo)..."
+        echo "127.0.0.1   go" | sudo tee -a /etc/hosts > /dev/null
+        echo_success "Added 'go' to /etc/hosts"
+    fi
+}
+
+# Setup LaunchAgent
+setup_launchagent() {
+    PLIST_DIR="$HOME/Library/LaunchAgents"
+    PLIST_FILE="$PLIST_DIR/com.user.golinks.plist"
+
+    echo_info "Setting up LaunchAgent..."
+
+    # Create LaunchAgents directory if it doesn't exist
+    mkdir -p "$PLIST_DIR"
+
+    # Find golinks executable path
+    GOLINKS_PATH=$(which golinks)
+    if [ -z "$GOLINKS_PATH" ]; then
+        echo_error "golinks command not found in PATH"
+        exit 1
+    fi
+
+    # Create plist file
+    cat > "$PLIST_FILE" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.user.golinks</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>$GOLINKS_PATH</string>
+        <string>--port</string>
+        <string>8080</string>
+        <string>--config</string>
+        <string>$HOME/.config/golinks/config.json</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>$HOME/.config/golinks/stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>$HOME/.config/golinks/stderr.log</string>
+</dict>
+</plist>
+EOF
+
+    echo_success "LaunchAgent plist created"
+}
+
+# Setup port forwarding (port 80 -> 8080)
+setup_port_forwarding() {
+    echo_info "Setting up port 80 forwarding to 8080..."
+
+    # Check if pf anchor file already exists
+    if [ -f "/etc/pf.anchors/golinks" ]; then
+        echo_warning "Port forwarding anchor already exists"
+    else
+        echo_info "Creating port forwarding rule (requires sudo)..."
+
+        # Create the anchor file
+        echo "rdr pass on lo0 inet proto tcp from any to 127.0.0.1 port 80 -> 127.0.0.1 port 8080" | sudo tee /etc/pf.anchors/golinks > /dev/null
+
+        echo_success "Port forwarding anchor created"
+    fi
+
+    # Check if pf.conf already includes our anchor
+    if sudo grep -q "golinks" /etc/pf.conf 2>/dev/null; then
+        echo_info "pf.conf already configured for golinks"
+    else
+        echo_info "Updating pf.conf (requires sudo)..."
+
+        # Backup pf.conf
+        sudo cp /etc/pf.conf /etc/pf.conf.backup.$(date +%Y%m%d%H%M%S)
+
+        # Add rdr-anchor after other rdr-anchor lines (with proper newline)
+        sudo sed -i '' '/^rdr-anchor "com.apple\/\*"/a\
+rdr-anchor "golinks"
+' /etc/pf.conf
+
+        # Add load anchor after the com.apple load anchor (with proper newline)
+        sudo sed -i '' '/^load anchor "com.apple" from "\/etc\/pf.anchors\/com.apple"/a\
+load anchor "golinks" from "/etc/pf.anchors/golinks"
+' /etc/pf.conf
+
+        echo_success "pf.conf updated"
+    fi
+
+    # Enable pfctl
+    echo_info "Enabling packet filtering..."
+    sudo pfctl -e 2>/dev/null || true
+    sudo pfctl -f /etc/pf.conf 2>/dev/null || {
+        echo_warning "Could not reload pf.conf. You may need to restart or manually run: sudo pfctl -f /etc/pf.conf"
+    }
+
+    echo_success "Port forwarding setup complete (80 -> 8080)"
+}
+
+# Start the service
+start_service() {
+    PLIST_FILE="$HOME/Library/LaunchAgents/com.user.golinks.plist"
+
+    echo_info "Starting golinks service..."
+
+    # Unload if already loaded
+    launchctl unload "$PLIST_FILE" 2>/dev/null || true
+
+    # Load the service
+    launchctl load "$PLIST_FILE"
+
+    # Wait for service to start
+    echo_info "Waiting for service to start..."
+    sleep 3
+
+    # Verify service is running
+    if curl -s http://localhost:8080/ | grep -q "Go Links" 2>/dev/null; then
+        echo_success "Service started successfully at http://localhost:8080"
+    else
+        echo_warning "Service may not be running. Check logs at ~/.config/golinks/"
+    fi
+}
+
+# Main installation flow
+main() {
+    echo -e "${GREEN}╔══════════════════════════════════════╗${NC}"
+    echo -e "${GREEN}║      GoLinks Installation Script     ║${NC}"
+    echo -e "${GREEN}╚══════════════════════════════════════╝${NC}"
+    echo ""
+
+    # Check if already installed
+    if check_installation; then
+        read -p "golinks is already installed. Reinstall? (y/N): " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            echo_info "Installation cancelled"
+            exit 0
+        fi
+    fi
+
+    # Run installation steps
+    install_uv
+    install_golinks
+    setup_config
+    setup_hosts
+    setup_launchagent
+    setup_port_forwarding
+    start_service
+
+    echo ""
+    echo -e "${GREEN}╔══════════════════════════════════════╗${NC}"
+    echo -e "${GREEN}║   Installation Complete! 🎉          ║${NC}"
+    echo -e "${GREEN}╚══════════════════════════════════════╝${NC}"
+    echo ""
+    echo "Usage examples:"
+    echo "  • Visit http://go to see the configured links"
+    echo "  • Use a link: open http://go/<slug>"
+    echo ""
+    echo "Logs are available at: ~/.config/golinks/"
+}
+
+# Run main function
+main

golinks-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src"]
+
+[project]
+name = "golinks"
+version = "1.0.0"
+description = "A local go links redirect service for URL shortcuts"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }  # Add your preferred license
+authors = [
+    { name = "Haran Rajkumar", email = "haranrajkumar97@gmail.com" },
+]
+keywords = ["golinks", "url-shortener", "redirect", "shortcuts"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "jinja2>=3.1.6",
+    "pydantic>=2.11.9",
+]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/golinks"
+Repository = "https://github.com/yourusername/golinks.git"
+Issues = "https://github.com/yourusername/golinks/issues"
+
+[project.scripts]
+golinks = "src.server:main"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.13.0",
+]
+
+
+
+[tool.pyright]
+reportUnusedCallResult = false
+typeCheckingMode = "standard"

golinks-1.0.0/src/models.py

@@ -0,0 +1,14 @@
+from pydantic import BaseModel, Field, RootModel
+from typing import Union, Dict
+
+
+class LinkTemplate(BaseModel):
+    template_url: str
+    defaults: Dict[str, str] = Field(default_factory=dict)
+
+
+LinkConfig = Union[str, LinkTemplate]
+
+
+class GoLinksConfig(RootModel):
+    root: Dict[str, LinkConfig]