cleanup: remove binaries and build artifacts from git tracking
Remove large files that should not be committed: - insertr binary (19MB) - generated Go executable - test-output/ and client-dist/ - build output directories - demo-site/insertr.js - generated from lib/dist/insertr.js - internal/content/assets/*.js - embedded build artifacts - outdated integration/version control summary files - log files (server.log) Update .gitignore to exclude: - Compiled binaries (insertr, insertr.exe) - Generated assets (demo-site/insertr.js, internal/content/assets/*.js) - Build output directories (test-output/, client-dist/) - Database files (*.db) and log files (*.log) - Air temporary files Repository size reduction: ~20MB+ of unnecessary tracked files removed
This commit is contained in:
32
.gitignore
vendored
32
.gitignore
vendored
@@ -68,9 +68,37 @@ insertr-cli/build-errors.log
|
||||
*.db
|
||||
*.sqlite
|
||||
*.sqlite3
|
||||
dev.db
|
||||
insertr.db
|
||||
integration.db
|
||||
test-ids.db
|
||||
|
||||
# Log files
|
||||
server.log
|
||||
*.log
|
||||
|
||||
# Local development files
|
||||
.local/
|
||||
|
||||
# Demo site generated files
|
||||
demo-site/insertr.js# Node.js root dependencies
|
||||
# Compiled binaries
|
||||
insertr
|
||||
insertr.exe
|
||||
/insertr
|
||||
/insertr.exe
|
||||
|
||||
# Generated/built assets
|
||||
demo-site/insertr.js
|
||||
demo-site/insertr.min.js
|
||||
internal/content/assets/insertr.js
|
||||
internal/content/assets/insertr.min.js
|
||||
|
||||
# Test and build output directories
|
||||
test-output/
|
||||
client-dist/
|
||||
output/
|
||||
|
||||
# Air temporary files
|
||||
tmp/
|
||||
.air/
|
||||
|
||||
# Node.js root dependencies
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# AGENTS.md - Developer Guide for Insertr
|
||||
|
||||
## Build/Test Commands
|
||||
Let me handle running and building the server. I run just dev in a different terminal, so you can just test the api directly, without spinning up an instance.
|
||||
- `just dev` - Full-stack development (recommended)
|
||||
- `just build` - Build entire project (Go binary + JS library)
|
||||
- `just build-lib` - Build JS library only
|
||||
@@ -28,4 +29,4 @@
|
||||
### Database
|
||||
- Use `sqlc` for Go database code generation
|
||||
- SQL files in `db/queries/`, schemas in `db/{sqlite,postgresql}/schema.sql`
|
||||
- Run `just sqlc` after schema changes
|
||||
- Run `just sqlc` after schema changes
|
||||
|
||||
@@ -1,125 +0,0 @@
|
||||
# Unified Binary Architecture Complete ✅
|
||||
|
||||
## 🎯 **What Was Accomplished**
|
||||
|
||||
Successfully refactored **insertr-cli** and **insertr-server** into a **unified `insertr` binary**, creating a **simpler, more maintainable architecture** while preserving all functionality.
|
||||
|
||||
## 🚀 **Unified Binary Experience**
|
||||
|
||||
### **Single Binary Commands**
|
||||
```bash
|
||||
./insertr enhance # 🔨 Build-time content injection
|
||||
./insertr serve # 🔌 Runtime API server
|
||||
./insertr --help # 📖 Complete command reference
|
||||
```
|
||||
|
||||
### **Simplified Development**
|
||||
```bash
|
||||
just dev # 🔥 Full-stack development (PRIMARY)
|
||||
just serve # API server only (development)
|
||||
just enhance # Build-time enhancement only
|
||||
```
|
||||
|
||||
### **Enhanced Build Pipeline**
|
||||
```bash
|
||||
just build # Now builds: Library + Unified Binary (single executable)
|
||||
npm run build # Same - builds complete stack via scripts/build.js
|
||||
```
|
||||
|
||||
### **Smart Configuration**
|
||||
- **YAML Configuration**: `insertr.yaml` with smart defaults
|
||||
- **Environment Variables**: `INSERTR_*` prefix for all settings
|
||||
- **CLI Flag Precedence**: Command-line flags override config and env vars
|
||||
- **Database Flexibility**: SQLite for development, PostgreSQL for production
|
||||
|
||||
## 📋 **Technical Architecture Changes**
|
||||
|
||||
### **1. Unified Command Structure**
|
||||
- **Single Binary**: `insertr` handles both enhance and serve operations
|
||||
- **Cobra CLI**: Professional command structure with subcommands
|
||||
- **Viper Configuration**: YAML + environment + CLI flag precedence
|
||||
- **Shared Database Layer**: Single source of truth for content models
|
||||
|
||||
### **2. Preserved Database Architecture**
|
||||
- **sqlc Code Generation**: Maintained type-safe database operations
|
||||
- **Multi-Database Support**: SQLite (development) and PostgreSQL (production)
|
||||
- **Version Control System**: Complete edit history with rollback capabilities
|
||||
- **Database Abstraction**: Runtime database type detection
|
||||
|
||||
### **3. Enhanced Build Integration**
|
||||
- `scripts/build.js` builds unified binary with embedded library assets
|
||||
- `justfile` updated for unified binary commands
|
||||
- `Air` configuration for hot reload during development
|
||||
- Single binary deployment for all use cases
|
||||
|
||||
### **4. Configuration Flexibility**
|
||||
- **YAML Config**: `insertr.yaml` for declarative configuration
|
||||
- **Environment Variables**: `INSERTR_*` prefixed for all settings
|
||||
- **CLI Precedence**: Command flags override file and env config
|
||||
- **Smart Defaults**: Zero-configuration development workflow
|
||||
|
||||
## 🔄 **Simplified Development Workflow**
|
||||
|
||||
### **Primary Development (Default)**
|
||||
```bash
|
||||
just dev # or npm run dev
|
||||
# Starts: insertr serve (8080) + Demo site (3000)
|
||||
# Complete CMS experience with unified binary
|
||||
```
|
||||
|
||||
### **Build-Time Enhancement**
|
||||
```bash
|
||||
just enhance # Build-time content injection
|
||||
./insertr enhance demo-site/ --output ./dist --mock
|
||||
./insertr enhance src/ --api https://cms.example.com
|
||||
```
|
||||
|
||||
### **Production Deployment**
|
||||
```bash
|
||||
./insertr serve --db "postgresql://user:pass@host/db"
|
||||
./insertr --config production.yaml serve
|
||||
```
|
||||
|
||||
## ✅ **Migration Benefits Achieved**
|
||||
|
||||
All functionality preserved with architectural improvements:
|
||||
- ✅ **Single Binary**: No more separate CLI and server binaries
|
||||
- ✅ **Shared Codebase**: Database models, validation, and logic unified
|
||||
- ✅ **Flexible Configuration**: YAML, environment, and CLI flag support
|
||||
- ✅ **Development Workflow**: Hot reload with `air` for unified binary
|
||||
- ✅ **Production Ready**: Same binary handles build-time and runtime
|
||||
- ✅ **Database Architecture**: Preserved sophisticated sqlc multi-DB setup
|
||||
|
||||
## 🏗️ **Architecture Diagram**
|
||||
|
||||
### **Before: Separate Binaries**
|
||||
```
|
||||
insertr-cli/ insertr-server/
|
||||
↓ ↓
|
||||
enhance serve
|
||||
↓ ↓
|
||||
Build-time Runtime
|
||||
```
|
||||
|
||||
### **After: Unified Binary**
|
||||
```
|
||||
insertr
|
||||
↙ ↘
|
||||
enhance serve
|
||||
↓ ↓
|
||||
Build-time Runtime
|
||||
↓ ↓
|
||||
Same Database Layer
|
||||
Same Configuration
|
||||
Same Content Models
|
||||
```
|
||||
|
||||
## 🎉 **Result**
|
||||
|
||||
The architecture is now **unified and maintainable**:
|
||||
- **Single Source of Truth** - No duplicate database or content logic
|
||||
- **Simplified Deployment** - One binary for all use cases
|
||||
- **Better Developer Experience** - Consistent configuration and commands
|
||||
- **Production Flexibility** - Build-time enhancement OR runtime API OR both
|
||||
|
||||
**Insertr unified binary is production-ready with improved maintainability!** 🚀
|
||||
122
TODO.md
122
TODO.md
@@ -362,3 +362,125 @@ PUT /api/content/{id}/draft
|
||||
5. **Graceful Degradation**: Fallback to basic editing if draft system fails
|
||||
|
||||
**Note**: Current architecture already supports foundation for all these enhancements through the unified Editor system and API client pattern.
|
||||
|
||||
## 🏗️ **Server-Hosted Static Sites Implementation** (Sept 2025)
|
||||
|
||||
### **✅ COMPLETED: Unified Binary HTTP Server**
|
||||
The HTTP server has been successfully implemented and is production-ready:
|
||||
- ✅ **Full REST API** - All content CRUD operations (`internal/api/handlers.go`)
|
||||
- ✅ **Multi-Database Support** - SQLite + PostgreSQL with sqlc-generated queries
|
||||
- ✅ **Authentication System** - JWT + mock tokens, ready for authentik integration
|
||||
- ✅ **Bulk Operations** - Efficient bulk content retrieval (`injector.go:56-96`)
|
||||
- ✅ **Content Enhancement** - Build-time content injection from database
|
||||
|
||||
### **🎯 NEW PRIORITY: Server-Hosted File Enhancement**
|
||||
|
||||
**Goal**: Enable real-time content updates for server-hosted static sites through database-driven file enhancement.
|
||||
|
||||
**Architecture**: Database as source of truth → Content changes → File updates → Immediate deployment
|
||||
|
||||
### **Phase 1: Core File Enhancement System**
|
||||
- [ ] **Extend enhancer.go** - Add `EnhanceInPlace()` method for in-place file modification
|
||||
- [ ] **Site Manager** - Create registration system for static site paths
|
||||
- [ ] **Handler Integration** - Hook file enhancement into `UpdateContent()` API calls
|
||||
- [ ] **Configuration Extension** - Add sites configuration to `insertr.yaml`
|
||||
|
||||
**Files to modify**:
|
||||
- `internal/content/enhancer.go` - Add in-place enhancement methods
|
||||
- `internal/api/handlers.go:225` - Integrate file enhancement trigger
|
||||
- `insertr.yaml` - Add sites configuration section
|
||||
- `cmd/serve.go` - Initialize site manager in server
|
||||
|
||||
### **Phase 2: Multi-Site Server Management**
|
||||
- [ ] **CLI Site Commands** - `insertr sites register/list/enhance`
|
||||
- [ ] **File Backup System** - Backup original files before enhancement
|
||||
- [ ] **Error Handling** - Graceful file permission and disk space handling
|
||||
- [ ] **Performance Optimization** - Selective file updates, change detection
|
||||
|
||||
### **Phase 3: Production Features**
|
||||
- [ ] **Authentik Integration** - OIDC authentication for production deployment
|
||||
- [ ] **Caddy Integration** - Reverse proxy configuration templates
|
||||
- [ ] **Monitoring & Logging** - Track enhancement operations and errors
|
||||
- [ ] **Multi-Environment** - Development vs production configuration
|
||||
|
||||
### **Implementation Approach: Leverage Existing Architecture**
|
||||
|
||||
**Reuse Existing Components**:
|
||||
- ✅ **Bulk Injection** - `injector.go:56-96` already handles efficient content injection
|
||||
- ✅ **Multi-Site Support** - `siteID` parameter used throughout API and database
|
||||
- ✅ **Authentication** - `auth.go:47-67` supports JWT tokens ready for authentik
|
||||
- ✅ **Content Client Interface** - `types.go:18-28` extensible for new features
|
||||
|
||||
**New Components** (minimal additions):
|
||||
- **Site Manager** - Register static site paths and manage file enhancement
|
||||
- **In-Place Enhancer** - Extend existing enhancer for file modification
|
||||
- **Configuration** - Extend YAML config for site registration
|
||||
|
||||
### **Target Deployment Architecture**
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Caddy Reverse Proxy │
|
||||
├─────────────────┬───────────────────┤
|
||||
│ Static Sites │ Insertr Server │
|
||||
│ /site1/* ────→ │ :8080/api/* │
|
||||
│ /site2/* ────→ │ Authentication │
|
||||
│ /admin/* ────→ │ File Enhancement │
|
||||
└─────────────────┴───────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────┐ ┌─────────────────┐
|
||||
│Static Files │ │ Database + │
|
||||
│/var/www/ │◄───┤ Enhancement │
|
||||
│ site1/ │ │ Engine │
|
||||
│ site2/ │ └─────────────────┘
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
**Content Update Workflow**:
|
||||
1. Editor makes content change → API call to `/api/content/{id}`
|
||||
2. Content saved to database (source of truth)
|
||||
3. File enhancement triggered → Static files updated in-place
|
||||
4. Changes immediately visible to visitors (served by Caddy)
|
||||
|
||||
### **Future CI/CD Integration Features** (Post-Server Implementation)
|
||||
|
||||
#### **External Build Trigger System**
|
||||
- **Webhook Integration**: Trigger external CI/CD pipelines when content changes
|
||||
- **GitHub Actions Templates**: Pre-built workflows for Hugo, Next.js, Jekyll + Insertr
|
||||
- **Platform Integrations**: Native Netlify, Vercel, CloudFlare Pages integration
|
||||
- **Build Status Tracking**: Monitor external build progress and deployment status
|
||||
|
||||
#### **Hybrid Deployment Models**
|
||||
- **File + Pipeline Mode**: Server-hosted sites with optional CI/CD rebuilds
|
||||
- **Content API Mode**: Headless CMS for external static site generators
|
||||
- **Multi-Environment**: Staging/production deployment coordination
|
||||
- **Build Caching**: Intelligent rebuilds based on content vs template changes
|
||||
|
||||
#### **Advanced Content Workflows**
|
||||
- **Scheduled Publishing**: Time-based content activation
|
||||
- **Content Approval**: Multi-user approval workflows before deployment
|
||||
- **A/B Testing**: Content variations for different user segments
|
||||
- **Rollback Integration**: Coordinate content rollbacks with deployment rollbacks
|
||||
|
||||
### **Draft System Foundation** (Ready for Extension)
|
||||
|
||||
**Current Architecture Supports**:
|
||||
- ✅ **Bulk Operations** - `injector.go:56-96` efficient for batch content updates
|
||||
- ✅ **Version Control** - Full version history with rollback capabilities
|
||||
- ✅ **Content Types** - Extensible type system ready for draft fields
|
||||
|
||||
**Future Draft Features**:
|
||||
- **Server-Side Drafts** - Extend `ContentItem` with `is_draft` field
|
||||
- **Batch Publishing** - Publish multiple draft items simultaneously
|
||||
- **Preview Mode** - View sites with draft content before publishing
|
||||
- **Auto-Save Drafts** - Background saving during editing sessions
|
||||
|
||||
### **Benefits of Server-Hosted Approach**
|
||||
|
||||
1. **✅ Immediate Deployment** - Content changes are live instantly
|
||||
2. **✅ Database Source of Truth** - No git-based workflow complexity
|
||||
3. **✅ Content-Only Updates** - No template rebuilds required
|
||||
4. **✅ Existing Infrastructure** - Leverages Caddy + authentik setup
|
||||
5. **✅ Performance** - Static file serving with dynamic content injection
|
||||
6. **✅ Multi-Site** - Single server manages multiple enhanced sites
|
||||
7. **✅ Zero Downtime** - Updates don't require site rebuilds or deploys
|
||||
|
||||
@@ -1,169 +0,0 @@
|
||||
# Version Control Implementation Summary
|
||||
|
||||
## 🎯 **What We Built**
|
||||
|
||||
A complete version control system for the Insertr CMS with user attribution, rollback functionality, and modern database architecture using sqlc.
|
||||
|
||||
## 🏗️ **Architecture Changes**
|
||||
|
||||
### **Database Layer (sqlc + Modern Schema)**
|
||||
- **sqlc Integration**: Type-safe Go database code generated from SQL
|
||||
- **Clean Schema**: `content` + `content_versions` tables with proper indexing
|
||||
- **User Attribution**: Track who made each change with timestamps
|
||||
- **Version History**: Complete edit history preserved automatically
|
||||
|
||||
### **API Enhancements**
|
||||
- **Version Endpoints**: `GET /{id}/versions`, `POST /{id}/rollback`
|
||||
- **User Attribution**: `X-User-ID` header support for all operations
|
||||
- **Automatic Versioning**: Current content archived before any update
|
||||
- **Clean Error Handling**: Proper HTTP status codes and error messages
|
||||
|
||||
### **Frontend Version Control UI**
|
||||
- **History Button**: Added to all edit forms
|
||||
- **Version Modal**: Professional GitHub-style version history display
|
||||
- **One-Click Rollback**: Restore any previous version instantly
|
||||
- **User Attribution**: Display who made each change and when
|
||||
- **Version Comparison**: Preview content changes before restoring
|
||||
|
||||
## 🔧 **Technical Implementation**
|
||||
|
||||
### **ID Generation System (Fixed)**
|
||||
- **Deterministic IDs**: Same content always generates same ID
|
||||
- **CLI ↔ JS Consistency**: Both systems use identical SHA-1 based algorithm
|
||||
- **Content-Based Versioning**: Content changes create new IDs naturally
|
||||
- **Developer Override**: HTML `id` attribute takes precedence over generated IDs
|
||||
|
||||
### **Database Schema**
|
||||
```sql
|
||||
-- Current content (latest versions only)
|
||||
CREATE TABLE content (
|
||||
id TEXT NOT NULL,
|
||||
site_id TEXT NOT NULL,
|
||||
value TEXT NOT NULL,
|
||||
type TEXT NOT NULL,
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
last_edited_by TEXT,
|
||||
PRIMARY KEY (id, site_id)
|
||||
);
|
||||
|
||||
-- Complete version history
|
||||
CREATE TABLE content_versions (
|
||||
version_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
content_id TEXT NOT NULL,
|
||||
site_id TEXT NOT NULL,
|
||||
value TEXT NOT NULL,
|
||||
type TEXT NOT NULL,
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
created_by TEXT
|
||||
);
|
||||
```
|
||||
|
||||
### **API Workflow Example**
|
||||
```bash
|
||||
# 1. Create content
|
||||
POST /api/content
|
||||
{"id": "hero-title", "value": "Original", "type": "text"}
|
||||
|
||||
# 2. Update (auto-archives current version)
|
||||
PUT /api/content/hero-title?site_id=demo
|
||||
{"value": "Updated content"}
|
||||
|
||||
# 3. View history
|
||||
GET /api/content/hero-title/versions?site_id=demo
|
||||
# Returns: [{"version_id": 1, "value": "Original", "created_by": "user"}]
|
||||
|
||||
# 4. Rollback
|
||||
POST /api/content/hero-title/rollback?site_id=demo
|
||||
{"version_id": 1}
|
||||
```
|
||||
|
||||
## 🎮 **User Experience**
|
||||
|
||||
### **Content Editor Workflow**
|
||||
1. **Click Edit** on any `class="insertr"` element
|
||||
2. **Professional Modal** opens with current content
|
||||
3. **View History** button shows version timeline
|
||||
4. **Version Modal** displays all changes with timestamps and authors
|
||||
5. **One-Click Restore** to any previous version
|
||||
6. **All Changes Tracked** automatically with user attribution
|
||||
|
||||
### **Developer Experience**
|
||||
- **Zero Configuration**: Still just add `class="insertr"`
|
||||
- **Hidden Complexity**: Version control happens transparently
|
||||
- **Full Control**: HTML `id` attribute overrides system-generated IDs
|
||||
- **Type Safety**: sqlc provides compile-time SQL validation
|
||||
- **Modern Tooling**: Professional database migration workflow
|
||||
|
||||
## 📊 **Features Delivered**
|
||||
|
||||
### ✅ **Core Version Control**
|
||||
- **Complete Edit History**: Every change preserved permanently
|
||||
- **User Attribution**: Track who made each change
|
||||
- **One-Click Rollback**: Restore any previous version instantly
|
||||
- **Automatic Versioning**: No manual intervention required
|
||||
|
||||
### ✅ **Professional UI**
|
||||
- **GitHub-Style History**: Familiar version control interface
|
||||
- **Version Comparison**: See what changed between versions
|
||||
- **User-Friendly Timestamps**: "2h ago", "yesterday", etc.
|
||||
- **Responsive Design**: Works on mobile and desktop
|
||||
|
||||
### ✅ **Developer Tools**
|
||||
- **sqlc Integration**: Type-safe database operations
|
||||
- **Clean Database Schema**: Proper indexing and relationships
|
||||
- **Development Commands**: `just server-generate`, `just server-clean-db`
|
||||
- **API Documentation**: Complete endpoint reference
|
||||
|
||||
### ✅ **Production Ready**
|
||||
- **SQLite → PostgreSQL**: Easy database migration path
|
||||
- **Proper Error Handling**: Informative error messages
|
||||
- **CORS Configured**: Multi-origin support for development
|
||||
- **Health Checks**: Monitoring and debugging endpoints
|
||||
|
||||
## 🚀 **What's Different Now**
|
||||
|
||||
### **Before: Basic CMS**
|
||||
- Simple content editing
|
||||
- No version history
|
||||
- Temporal ID conflicts
|
||||
- No user tracking
|
||||
|
||||
### **After: Professional CMS**
|
||||
- Complete version control with rollback
|
||||
- User attribution for all changes
|
||||
- Deterministic ID system (CLI ↔ JS consistent)
|
||||
- Modern database architecture (sqlc)
|
||||
- Professional editing UI with history
|
||||
- Production-ready API with proper error handling
|
||||
|
||||
## 📋 **Development Workflow Enhanced**
|
||||
|
||||
### **New Commands**
|
||||
```bash
|
||||
# Generate database code from SQL
|
||||
just server-generate
|
||||
|
||||
# Clean development database
|
||||
just server-clean-db
|
||||
|
||||
# Full version control development
|
||||
just dev # Now includes version history UI
|
||||
```
|
||||
|
||||
### **Updated Files**
|
||||
- **Database**: `insertr-server/db/` - Complete sqlc setup
|
||||
- **API**: `internal/api/handlers.go` - Version control endpoints
|
||||
- **Frontend**: `lib/src/ui/form-renderer.js` - History modal UI
|
||||
- **Docs**: Updated README.md with version control features
|
||||
|
||||
## 🎯 **Result**
|
||||
|
||||
Insertr now provides **WordPress-style version control** with:
|
||||
- **Professional editing experience**
|
||||
- **Complete change tracking**
|
||||
- **Easy rollback functionality**
|
||||
- **Modern database architecture**
|
||||
- **Type-safe backend code**
|
||||
|
||||
All while maintaining the **"zero configuration"** philosophy - developers still just add `class="insertr"` and get a complete CMS with version control.
|
||||
Reference in New Issue
Block a user