insertr/COMMANDS.md

# Insertr Command Reference

Complete reference for the unified `insertr` binary commands, configuration, and usage patterns.

## 🔧 Command Overview

```bash
insertr [global-flags] <command> [command-flags] [arguments]
```

## 📚 Global Flags

Available for all commands:

| Flag | Environment Variable | Description | Default |
|------|---------------------|-------------|---------|
| `--config` | N/A | Config file path | `./insertr.yaml` |
| `--db` | `INSERTR_DB_PATH` | Database path or connection string | `./insertr.db` |
| `--api-url` | `INSERTR_API_URL` | Remote content API URL | `""` |
| `--api-key` | `INSERTR_API_KEY` | API authentication key | `""` |
| `--site-id` | `INSERTR_SITE_ID` | Site identifier for content | `"demo"` |
| `--help` | N/A | Show help information | N/A |
| `--version` | N/A | Show version information | N/A |

## 🔨 enhance Command

Build-time content injection - processes HTML files and injects database content.

```bash
insertr enhance [input-dir] [flags]
```

### Arguments
- `input-dir` - Directory containing HTML files to enhance (required)

### Flags
| Flag | Description | Default |
|------|-------------|---------|
| `--output`, `-o` | Output directory for enhanced files | `./dist` |
| `--mock` | Use mock content for development | `true` |

### Examples

```bash
# Basic enhancement with mock data
./insertr enhance demo-site/

# Production build with custom output
./insertr enhance src/ --output ./build --mock=false

# Use remote API for content  
./insertr enhance src/ --api-url https://cms.example.com --api-key xyz123

# Use local database
./insertr enhance src/ --db ./content.db

# Custom site ID
./insertr enhance src/ --site-id production
```

### Content Sources Priority
1. Remote API (if `--api-url` provided)
2. Local database (if `--db` points to valid database)
3. Mock content (if `--mock=true` or fallback)

## 🔌 serve Command

Runtime API server - provides HTTP endpoints for content management and server-hosted static site enhancement.

```bash
insertr serve [flags]
```

### Flags
| Flag | Description | Default |
|------|-------------|---------|
| `--port`, `-p` | HTTP server port | `8080` |
| `--dev-mode` | Enable development mode features | `false` |

### Examples

```bash
# Development server
./insertr serve --dev-mode

# Production server
./insertr serve --port 80

# Custom database
./insertr serve --db ./production.db

# PostgreSQL database
./insertr serve --db "postgresql://user:pass@localhost:5432/insertr"

# Custom configuration
./insertr --config production.yaml serve
```

### Server-Hosted Static Sites

When running `insertr serve`, the server automatically:
- **Registers sites** from `insertr.yaml` configuration
- **Enhances static files** with latest database content
- **Auto-updates files** when content changes via API


**Live Enhancement Process:**
1. Content updated via API → Database updated
2. If site has `auto_enhance: true` → File enhancement triggered
3. Static files updated in-place → Changes immediately live

### API Endpoints

When running `insertr serve`, these endpoints are available:

#### Health Check
- `GET /health` - Server health status

#### Content Management
- `GET /api/content?site_id={site}` - Get all content for site
- `GET /api/content/{id}?site_id={site}` - Get single content item
- `GET /api/content/bulk?site_id={site}&ids[]={id1}&ids[]={id2}` - Get multiple items
- `POST /api/content` - Create or update content (upsert)
- `DELETE /api/content/{id}?site_id={site}` - Delete content

#### Site Enhancement
- `POST /api/enhance?site_id={site}` - Manually trigger site file enhancement

#### Version Control
- `GET /api/content/{id}/versions?site_id={site}` - Get content history
- `POST /api/content/{id}/rollback` - Rollback to previous version

#### Authentication
- `GET /auth/login` - Initiate OAuth flow (returns redirect URL for Authentik)
- `GET /auth/callback` - OAuth callback handler (processes authorization code)

### Content Management API Details

#### Create/Update Content (Upsert)
```
POST /api/content[?site_id={site}]
```

**Request Body:**
```json
{
  "id": "optional-content-id",
  "site_id": "site-identifier",
  "value": "content-value",
  "type": "text|markdown|link",
  "element_context": {
    "tag": "h1",
    "classes": ["insertr", "title"],
    "original_content": "Default Title",
    "parent_context": "hero-section"
  }
}
```

**Key Features:**
- **Automatic ID Generation**: If no `id` provided, generates deterministic ID from `element_context`
- **Content Type Detection**: Automatically determines type if not specified
- **Version History**: Preserves existing content as version before update
- **Flexible Site ID**: Can be provided in URL parameter or request body
- **Auto-Enhancement**: Triggers file enhancement if site has `auto_enhance: true`

**Response:**
```json
{
  "id": "generated-or-provided-id",
  "site_id": "site-identifier", 
  "value": "content-value",
  "type": "text|markdown|link",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "last_edited_by": "user-id"
}
```

**Usage Examples:**

```bash
# Create with automatic ID generation
curl -X POST http://localhost:8080/api/content?site_id=demo \
  -H "Content-Type: application/json" \
  -d '{
    "value": "New Homepage Title",
    "element_context": {
      "tag": "h1",
      "classes": ["insertr"],
      "original_content": "Welcome"
    }
  }'

# Update existing content by ID
curl -X POST http://localhost:8080/api/content \
  -H "Content-Type: application/json" \
  -d '{
    "id": "homepage-title-abc123",
    "site_id": "demo",
    "value": "Updated Title",
    "type": "text"
  }'

# Create markdown content
curl -X POST http://localhost:8080/api/content?site_id=demo \
  -H "Content-Type: application/json" \
  -d '{
    "value": "# New Article\n\nThis is **markdown** content.",
    "type": "markdown",
    "element_context": {
      "tag": "div",
      "classes": ["insertr", "content"]
    }
  }'
```

## ⚙️ Configuration

### YAML Configuration File

Default file: `insertr.yaml`

```yaml
# Database configuration
database:
  path: "./insertr.db"        # SQLite file or PostgreSQL connection

# Remote API configuration  
api:
  url: ""                     # Content API URL
  key: ""                     # API key

# Server configuration
server:
  port: 8080                  # HTTP port
  dev_mode: false             # Development mode

# Build configuration
build:
  input: "./src"              # Default input directory
  output: "./dist"            # Default output directory

# Authentication configuration
auth:
  provider: "mock"            # "mock", "authentik"
  jwt_secret: ""              # JWT signing secret (auto-generated in dev)
  oidc:                       # Authentik OIDC configuration
    endpoint: ""              # https://auth.example.com/application/o/insertr/
    client_id: ""             # OAuth2 client ID
    client_secret: ""         # OAuth2 client secret

# Global settings
site_id: "demo"              # Site identifier
mock_content: false          # Use mock data
```

### Environment Variables

All configuration can be set via environment variables:

```bash
export INSERTR_DB_PATH="./content.db"
export INSERTR_API_URL="https://api.example.com"
export INSERTR_API_KEY="your-api-key"
export INSERTR_SITE_ID="production"

# Authentication environment variables (recommended for production)
export AUTHENTIK_CLIENT_SECRET="your-oidc-secret"
export AUTHENTIK_ENDPOINT="https://auth.example.com/application/o/insertr/"

./insertr serve
```

### Configuration Precedence

1. **CLI flags** (highest priority)
2. **Environment variables**
3. **YAML configuration file**
4. **Built-in defaults** (lowest priority)

## 📋 Usage Patterns

### Development Workflow

```bash
# Start full development environment
just dev                     # Uses justfile for convenience

# Manual development setup
./insertr serve --dev-mode --db ./dev.db &
npm run demo                 # Start demo site

# Hot reload development
air                         # Uses .air.toml configuration
```

### Production Deployment

```bash
# Build static site with content
./insertr enhance ./src --output ./dist --api-url https://api.prod.com

# Start production API server with authentication
export AUTHENTIK_CLIENT_SECRET="prod-secret"
./insertr serve --db "postgresql://user:pass@db:5432/prod"

# With custom configuration
./insertr --config ./production.yaml serve
```

### Authentication Setup

#### Mock Authentication (Development)
```bash
# Default - no setup required
./insertr serve --dev-mode

# Configuration
auth:
  provider: "mock"
```

#### Authentik OIDC (Production)
```bash
# Set environment variables (recommended)
export AUTHENTIK_CLIENT_SECRET="your-secret-from-authentik"
export AUTHENTIK_ENDPOINT="https://auth.example.com/application/o/insertr/"

# Start server
./insertr serve
```

**Required Authentik Configuration:**
1. Create OAuth2/OIDC Provider in Authentik
2. Set redirect URI: `https://your-domain.com/auth/callback`
3. Note the endpoint URL and client credentials
4. Configure in `insertr.yaml` or environment variables

### CI/CD Integration

```yaml
# GitHub Actions example
- name: Build with Insertr
  run: |
    ./insertr enhance ./public --output ./dist
    
- name: Deploy enhanced site
  uses: peaceiris/actions-gh-pages@v3
  with:
    publish_dir: ./dist
```

## 🚨 Error Handling

### Common Issues

**Database Connection Errors:**
```bash
# Check database path
./insertr --db ./nonexistent.db serve
# Error: failed to initialize database

# Solution: Verify database path or use --mock for development
./insertr serve --dev-mode  # Creates ./insertr.db automatically
```

**Port Already in Use:**
```bash
# Error: listen tcp :8080: bind: address already in use

# Solution: Use different port
./insertr serve --port 3001
```

**Missing Input Directory:**
```bash
# Error: Input directory does not exist

# Solution: Verify path exists
ls -la ./src
./insertr enhance ./src
```

## 🔍 Debugging

### Verbose Logging

```bash
# Enable development mode for more detailed output
./insertr serve --dev-mode

# Check server health
curl http://localhost:8080/health
```

### Configuration Validation

```bash
# Test configuration loading
./insertr --config ./test.yaml --help

# Verify environment variables
./insertr serve --help  # Shows resolved configuration values
```

---

For more examples and integration patterns, see:
- [Main README](README.md) - Getting started and overview
- [Integration Summary](INTEGRATION-SUMMARY.md) - Architecture details
- [Development Guide](DEVELOPMENT.md) - Contributing and setup