Merge pull request #259 from jaypatrick/master

Reverse merge from master to dev

Author: jaypatrick

.dockerignore

@@ -0,0 +1,60 @@
+# Git
+.git
+.gitignore
+.gitattributes
+
+# Environment files (secrets should be passed via docker-compose or -e flag)
+.env.local
+.env.*.local
+.envrc
+
+# Node
+node_modules
+npm-debug.log
+yarn-error.log
+
+# Deno
+.deno/
+
+# Build artifacts
+dist/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+data/
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test coverage
+coverage/
+coverage.lcov
+
+# Wrangler
+.wrangler/
+worker-configuration.d.ts
+.deployment-version.json
+
+# Documentation
+*.md
+!README.md
+
+# CI/CD
+.github/
+
+# Examples
+examples/
+
+# Output
+output/
+
+# Logs
+*.log

.env

@@ -0,0 +1,14 @@
+# Base environment variables shared across all environments
+# Loaded first by .envrc, then overlaid with .env.$ENV and .env.local
+# DO NOT put secrets here - use .env.local instead
+
+# Compiler version
+COMPILER_VERSION=0.11.4
+
+# Server port (default: 8787)
+PORT=8787
+
+# NOTE: Do not set DENO_DIR globally here, as this file is loaded in CI/GitHub Actions
+# and /app/.deno may not exist or be writable. Configure DENO_DIR only in
+# environment-specific files (e.g. .env.docker) or in container configs.
+# DENO_DIR=/app/.deno

.env.README.md

@@ -0,0 +1,169 @@
+# Environment Configuration
+
+This project uses a layered environment configuration system powered by `.envrc` and `direnv`.
+
+## How It Works
+
+Environment variables are loaded in the following order (later files override earlier ones):
+
+1. **`.env`** - Base configuration shared across all environments (committed to git)
+2. **`.env.$ENV`** - Environment-specific configuration (committed to git)
+3. **`.env.local`** - Local overrides and secrets (NOT committed to git)
+
+The `$ENV` variable is automatically determined by your current git branch:
+
+| Git Branch              | Environment   | Loaded File         |
+| ----------------------- | ------------- | ------------------- |
+| `main` or `master`      | `production`  | `.env.production`   |
+| `dev` or `develop`      | `development` | `.env.development`  |
+| Other branches          | `local`       | `.env.local`        |
+| Custom branch with file | Custom        | `.env.$BRANCH_NAME` |
+
+## File Structure
+
+```
+.env                  # Base config (PORT, COMPILER_VERSION, etc.)
+.env.development      # Development-specific (test API keys, local DB)
+.env.production       # Production-specific (placeholder values)
+.env.local            # Your personal secrets (NEVER commit this!)
+.env.example          # Template showing all available variables
+```
+
+## Setup Instructions
+
+### 1. Enable direnv (if not already installed)
+
+```bash
+# macOS
+brew install direnv
+
+# Add to your shell config (~/.zshrc)
+eval "$(direnv hook zsh)"
+```
+
+### 2. Allow the .envrc file
+
+```bash
+direnv allow
+```
+
+You should see: `✅ Loaded environment: development (branch: dev)`
+
+### 3. Create your .env.local file
+
+```bash
+cp .env.example .env.local
+```
+
+Then edit `.env.local` with your actual secrets and API keys.
+
+## What Goes Where?
+
+### `.env` (Committed)
+
+- Non-sensitive defaults
+- Port numbers
+- Version numbers
+- Public configuration
+
+### `.env.development` / `.env.production` (Committed)
+
+- Environment-specific defaults
+- Test API keys (development only)
+- Environment-specific feature flags
+- Non-secret configuration
+
+### `.env.local` (NOT Committed)
+
+- **ALL secrets and API keys**
+- Database connection strings
+- Authentication tokens
+- Personal overrides
+
+## Wrangler Integration
+
+The `wrangler.toml` configuration supports environment-based deployments:
+
+```bash
+# Development deployment
+wrangler deploy --env development
+
+# Production deployment
+wrangler deploy --env production
+```
+
+Environment variables from `.env.local` are automatically available during local development (`wrangler dev`).
+
+For production deployments, secrets should be set using:
+
+```bash
+wrangler secret put ADMIN_KEY --env production
+wrangler secret put TURNSTILE_SECRET_KEY --env production
+```
+
+## Troubleshooting
+
+### Environment not loading?
+
+```bash
+# Re-allow the .envrc
+direnv allow
+
+# Check what's loaded
+direnv exec . env | grep DATABASE_URL
+```
+
+### Wrong environment?
+
+Check your git branch:
+
+```bash
+git branch --show-current
+```
+
+The `.envrc` automatically maps your branch to an environment.
+
+### Variables not available?
+
+Make sure:
+
+1. You've created `.env.local` from `.env.example`
+2. You've run `direnv allow`
+3. The variable exists in one of the .env files
+
+## Security Best Practices
+
+- ✅ **DO** commit `.env`, `.env.development`, `.env.production`
+- ✅ **DO** use test/dummy values in committed files
+- ✅ **DO** put all secrets in `.env.local`
+- ❌ **DON'T** commit `.env.local`
+- ⚠️ **BE CAREFUL** with `.envrc` — it is committed as part of the env-loading system, so never put secrets or credentials in it
+- ❌ **DON'T** put real secrets in any committed file
+- ❌ **DON'T** commit production credentials
+
+## GitHub Actions Integration
+
+This environment system works seamlessly in GitHub Actions workflows. See [.github/ENV_SETUP.md](.github/ENV_SETUP.md) for detailed documentation.
+
+### Quick Start
+
+```yaml
+steps:
+    - uses: actions/checkout@v4
+
+    - name: Load environment variables
+      uses: ./.github/actions/setup-env
+
+    - name: Use environment variables
+      run: echo "Version: $COMPILER_VERSION"
+```
+
+The action automatically:
+
+- Detects environment from branch name
+- Loads `.env` and `.env.$ENV` files
+- Exports variables to workflow
+
+## Environment Variables Reference
+
+See `.env.example` for a complete list of available variables and their purposes.

.env.development

@@ -0,0 +1,11 @@
+# Development environment configuration
+# Loaded when on dev/develop branch
+# Secrets should go in .env.local instead
+
+# Database URL for local development (SQLite)
+DATABASE_URL="file:./data/adblock.db"
+
+# Cloudflare Turnstile test keys (always passes in testing)
+# Get production keys from https://dash.cloudflare.com/?to=/:account/turnstile
+TURNSTILE_SITE_KEY=1x00000000000000000000AA
+TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA

.env.example

@@ -1,27 +1,42 @@
-# Environment variables for Docker deployment
+# ============================================================================
+# Environment Variables Template
+# ============================================================================
+# Copy this file to .env.local and fill in your actual values
+# 
+# Environment Loading Order (via .envrc):
+#   1. .env           - Base configuration (committed)
+#   2. .env.$ENV      - Environment-specific (.env.development or .env.production)
+#   3. .env.local     - Local overrides and secrets (NOT committed)
+#
+# The $ENV variable is determined by your git branch:
+#   - main/master    → production
+#   - dev/develop    → development
+#   - other branches → local (or branch-specific if .env.$BRANCH exists)
+# ============================================================================
 
-# Database URL for Prisma/SQLite storage
-# This is used by PrismaStorageAdapter for local caching
-# Default: file:./data/adblock.db
-DATABASE_URL=file:./data/adblock.db
+# ===== Database Configuration =====
+# Local development (SQLite)
+DATABASE_URL="file:./data/adblock.db"
 
-# Compiler version
-COMPILER_VERSION=0.8.3
+# Direct connection string for migrations and introspection
+DIRECT_DATABASE_URL="postgres://your_user:your_password@db.prisma.io:5432/postgres?sslmode=require&pool=true"
 
-# Server port (default: 8787)
-PORT=8787
+# Prisma Accelerate connection string
+PRISMA_DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/?api_key=your_api_key_here"
 
-# Deno cache directory (default: /app/.deno)
-DENO_DIR=/app/.deno
+# Wrangler Hyperdrive local connection
+WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE=postgresql://user:password@host:5432/postgres?sslmode=verify-full&sslrootcert=system
 
-# Cloudflare Turnstile Configuration
+# ===== Cloudflare Turnstile =====
 # Get your keys from https://dash.cloudflare.com/?to=/:account/turnstile
 # Site key (public - used in the frontend widget)
-TURNSTILE_SITE_KEY=
+TURNSTILE_SITE_KEY=your_site_key_here
 # Secret key (private - used for server-side validation)
-TURNSTILE_SECRET_KEY=
+TURNSTILE_SECRET_KEY=your_secret_key_here
 
+# ===== API Keys =====
 # Admin API key for storage management endpoints
-# Used to authenticate requests to /api/admin/* endpoints
-ADMIN_KEY=
-OPTIMIZE_API_KEY=
+ADMIN_KEY="your_admin_key_here"
+
+# Optimize API key
+OPTIMIZE_API_KEY="your_optimize_api_key_here"

.env.production

@@ -0,0 +1,18 @@
+# Production environment configuration
+# Loaded when on main/master branch
+#
+# This file is committed to git and must only contain non-secret defaults/placeholders.
+# Real production secrets must be provided via your deployment environment's secret management
+# (e.g. Cloudflare Wrangler `wrangler secret put` / dashboard), not via this file or other committed env files.
+
+# Production database default - override via environment variables or .env.local for local development.
+# Do not store real production secrets in this file.
+DATABASE_URL=file:./data/adblock.db
+
+# Cloudflare Turnstile - placeholder values only.
+# Get your keys from https://dash.cloudflare.com/?to=/:account/turnstile
+# In production (e.g. Cloudflare Workers), configure real keys via secrets / environment variables
+# such as `wrangler secret put`, not in .env.production or .env.local.
+# Leave empty to disable Turnstile verification (or set to test keys for development).
+TURNSTILE_SITE_KEY=
+TURNSTILE_SECRET_KEY=

.envrc

@@ -0,0 +1,45 @@
+# ==============================
+# Universal direnv dotenv loader (Zsh layered merge)
+# ==============================
+
+# Watch for changes in env files
+watch_file .env .env.local .env.development .env.production
+
+# If inside a Git repo, also watch branch changes
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  watch_file "$(git rev-parse --show-toplevel)/.git/HEAD"
+  
+  # Detect current branch
+  GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "default")
+  
+  # Map branch to ENV
+  case "$GIT_BRANCH" in
+    main|master)
+      ENV="production"
+      ;;
+    develop|dev)
+      ENV="development"
+      ;;
+    *)
+      if [[ -f ".env.$GIT_BRANCH" ]]; then
+        ENV="$GIT_BRANCH"
+      else
+        ENV="local"
+      fi
+      ;;
+  esac
+else
+  ENV="development"
+  GIT_BRANCH="(no-git)"
+fi
+
+# Load env vars using direnv's built-in dotenv loader (preserves proper quoting/escaping)
+# Files are loaded in a layered order without clearing existing variables.
+
+# Load files in layered order
+dotenv_if_exists ".env"
+dotenv_if_exists ".env.$ENV"
+dotenv_if_exists ".env.local"
+
+# Status message
+echo "✅ Loaded environment: $ENV (branch: $GIT_BRANCH)"