Add Go CLI with container expansion parser and development server

- Implement Go-based CLI for build-time HTML enhancement - Add container expansion: div.insertr auto-expands to viable children - Create servedev command with live development workflow - Add Air configuration for automatic rebuilds and serving - Enable transition from runtime JS to build-time enhancement approach
2025-09-02 22:58:59 +02:00
parent afd4879cef
commit 0e84af98bc
13 changed files with 1429 additions and 1 deletions
--- a/RESEARCH.md
+++ b/RESEARCH.md
@@ -0,0 +1,551 @@
+# CMS Approaches and Workflows: Comprehensive Research
+
+## Executive Summary
+
+This document analyzes different Content Management System (CMS) approaches, their workflows, and architectural patterns to inform the strategic direction of Insertr CMS. Through extensive research and strategic iteration, we've identified a unique positioning as "The Tailwind of CMS" - an HTML enhancement service that adds editing capabilities to any static site without architectural changes.
+
+## Table of Contents
+
+1. [CMS Architecture Patterns](#cms-architecture-patterns)
+2. [Content Workflow Analysis](#content-workflow-analysis)
+3. [Rebuild Strategy Comparison](#rebuild-strategy-comparison)
+4. [Strategic Pivot: HTML Enhancement Approach](#strategic-pivot-html-enhancement-approach)
+5. [Competitive Landscape](#competitive-landscape)
+6. [Market Positioning: "The Tailwind of CMS"](#market-positioning-the-tailwind-of-cms)
+7. [Technical Implementation](#technical-implementation)
+8. [Strategic Recommendations](#strategic-recommendations)
+
+---
+
+## CMS Architecture Patterns
+
+### 1. Traditional CMS (WordPress, Drupal)
+**Architecture**: Monolithic, database-driven, server-side rendering
+**Content Flow**: Database → Server → HTML → Browser
+**Deployment**: Server hosting, automatic updates, runtime content changes
+
+**Pros:**
+- Immediate content updates
+- Rich ecosystem of plugins/themes
+- Non-technical user friendly
+- Mature tooling and community
+
+**Cons:**
+- Security vulnerabilities
+- Performance bottlenecks
+- Server maintenance overhead
+- Vendor lock-in to hosting stack
+
+**Example Workflow:**
+```
+Editor → WordPress Admin → Database → Live Site
+(Immediate, no build process)
+```
+
+### 2. Headless/API-First CMS (Contentful, Strapi, Sanity)
+**Architecture**: API backend + Frontend application
+**Content Flow**: API Database → GraphQL/REST → Static Build/Runtime → Browser
+**Deployment**: Separate API server + Static/Dynamic frontend
+
+**Pros:**
+- Flexible frontend technology choices
+- Scalable API architecture
+- Multi-channel content delivery
+- Developer-friendly GraphQL/REST APIs
+
+**Cons:**
+- Complex setup and configuration
+- API dependency for content
+- Runtime performance considerations
+- Higher technical complexity
+
+**Example Workflow:**
+```
+Editor → Headless CMS Admin → API → Webhook → Build Process → Static Site
+(Build-dependent, but flexible)
+```
+
+### 3. Git-Based CMS (Decap, Forestry, CloudCannon, TinaCMS)
+**Architecture**: Git repository as content database + Admin interface
+**Content Flow**: Git Files → Admin UI → Git Commits → Static Site Generator → Browser
+**Deployment**: Git-triggered builds, static site deployment
+
+**Pros:**
+- Version control for content
+- Developer-friendly Git workflow
+- Static site performance benefits
+- Backup and rollback capabilities
+
+**Cons:**
+- Rebuild requirements for changes
+- Git complexity for non-technical users
+- Limited real-time collaboration
+- Build time delays
+- **File mapping complexity**
+
+**Example Workflow:**
+```
+Editor → Git-based Admin → Git Commit → Build Trigger → Static Site
+(Git-dependent, build-required)
+```
+
+### 4. Visual/Page Builder CMS (Webflow, Wix, Builder.io)
+**Architecture**: Visual interface + Hosted rendering engine
+**Content Flow**: Visual Editor → Proprietary Database → Rendered Pages → Browser
+**Deployment**: Platform-hosted, automatic deployment
+
+**Pros:**
+- No-code visual editing
+- Immediate visual feedback
+- Built-in hosting and optimization
+- Designer-friendly interface
+
+**Cons:**
+- Vendor lock-in
+- Limited customization depth
+- Export/migration difficulties
+- Higher costs for custom needs
+
+### 5. **HTML Enhancement Pattern (Insertr's Approach)**
+**Architecture**: Build-time content injection + Conditional editor loading
+**Content Flow**: Static HTML → Enhancement CLI → Database Content → Enhanced Site
+**Deployment**: Standard static site deployment with editing capabilities
+
+**Pros:**
+- Zero runtime overhead for visitors
+- Works with any static site generator
+- No architectural changes required
+- Database-backed content storage
+- Framework-agnostic approach
+
+**Cons:**
+- Build-dependent for content updates
+- Requires enhancement step in build process
+
+**Example Workflow:**
+```
+Static Site Build → Insertr Enhancement CLI → Enhanced HTML → Deploy
+                      ↓
+                Database Content Injection + Editor Loading
+```
+
+---
+
+## Content Workflow Analysis
+
+### Immediate Update Pattern
+**Used by**: WordPress, Webflow, Traditional CMS
+**Flow**: Edit → Save → Live (0-5 seconds)
+**Benefits**: Instant feedback, simple mental model
+**Drawbacks**: No review process, potential for mistakes
+
+### Build-Dependent Pattern
+**Used by**: Gatsby + Contentful, Decap CMS, Hugo workflows
+**Flow**: Edit → Save → Build → Deploy (2-10 minutes)
+**Benefits**: Review process, optimized output, version control
+**Drawbacks**: Slow feedback loop, build complexity
+
+### Enhancement Pattern (Insertr's Approach)
+**Flow**: Edit (cached) → Batch Publish → Enhanced Rebuild → Deploy
+**Benefits**: 
+- Static performance for visitors
+- Rich editing experience for editors
+- Batched updates reduce build frequency
+- Zero configuration required
+**Drawbacks**: 2-5 minute delay for content changes to go live
+
+---
+
+## Rebuild Strategy Comparison
+
+### The "Decap Problem": Every Edit Triggers Rebuild
+**Issue**: Each content change commits to Git → triggers full site rebuild
+**Impact**: 
+- Slow feedback (2-10 minute delays)
+- Expensive build resources
+- Poor user experience for iterative editing
+- CI/CD queue bottlenecks
+- **File mapping configuration complexity**
+
+### Insertr's Solution: Build-Time Enhancement
+**Strategy**: 
+1. Static site builds normally (Hugo, Next.js, etc.)
+2. Enhancement CLI reads built HTML + fetches latest content
+3. CLI injects current content into HTML + adds editing hooks
+4. Deploy enhanced static site
+5. Editors trigger batched rebuilds only when publishing
+
+**Benefits**:
+- Eliminates file mapping complexity
+- Reduces rebuild frequency through batching
+- Maintains pure static performance
+- Works with any SSG without configuration
+
+---
+
+## Strategic Pivot: HTML Enhancement Approach
+
+### Core Insight: Avoid File/Git Mapping Complexity
+
+**Problem with Git-Based Approach**:
+- Mapping `data-content-id` to files/fields requires configuration
+- Different SSGs have different file conventions
+- Merge conflicts in collaborative editing
+- Schema drift as files change
+- Framework coupling issues
+
+**Solution: Database + Build-Time Injection**:
+- Simple key-value storage: `content_id → content_value`
+- No file mapping needed
+- Framework agnostic
+- Conflict-free collaborative editing
+- Audit trails and change tracking
+
+### New Architecture: "Editing as a Service"
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   Static Site   │    │  Enhancement CLI │    │   Enhanced      │
+│   Generator     │    │                  │    │   Deployment    │
+│                 │    │                  │    │                 │
+│ Hugo/Next.js/   │───▶│ Parse HTML       │───▶│ Static Site     │
+│ Jekyll/etc.     │    │ Inject Content   │    │ + Editing       │
+│                 │    │ Add Editor Hooks │    │ + Smart Loading │
+│ Outputs:        │    │                  │    │                 │
+│ Pure HTML       │    │ Database ←→ API  │    │ Zero Overhead   │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+```
+
+### GitHub Actions Integration Example
+
+```yaml
+# .github/workflows/deploy.yml
+name: Build and Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # 1. Standard static site build
+      - uses: actions/checkout@v3
+      - name: Build static site
+        run: hugo --minify
+        
+      # 2. Enhance with Insertr
+      - name: Add editing capabilities
+        run: npx @insertr/enhance ./public --output ./dist --api-url ${{ secrets.INSERTR_API_URL }}
+        
+      # 3. Deploy enhanced site
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          publish_dir: ./dist
+```
+
+---
+
+## Competitive Landscape
+
+### Market Leaders Analysis
+
+#### CloudCannon
+**Position**: Enterprise Git-based CMS
+**Strengths**: 
+- Mature visual editing
+- Multi-SSG support
+- Agency-focused features
+- Robust hosting integration
+
+**Weaknesses**:
+- Complex setup process (days of configuration)
+- Expensive pricing model ($45+/month)
+- Opinionated workflow requirements
+- Heavy platform lock-in
+- Component-based editing only
+
+**Target Market**: Digital agencies, enterprise teams, complex multi-site setups
+
+#### TinaCMS
+**Position**: Git + API hybrid, developer-friendly
+**Strengths**:
+- React-based editing
+- Git workflow with API preview
+- Open source with cloud offering
+- Developer-centric approach
+
+**Weaknesses**:
+- React/Next.js focused (limited framework support)
+- Still requires significant setup
+- Complex architecture
+- Schema configuration required
+
+**Target Market**: React developers, Next.js sites, developer-first teams
+
+#### Decap CMS (formerly Netlify CMS)
+**Position**: Simple Git-based editing
+**Strengths**:
+- Easy setup
+- Framework agnostic
+- Open source
+- Simple mental model
+
+**Weaknesses**:
+- Poor editing UX (form-based)
+- Constant rebuild issue
+- Limited customization
+- Maintenance mode concerns
+
+**Target Market**: Individual developers, simple blogs, basic static sites
+
+### Market Gap Analysis
+
+#### Under-Served Segments:
+1. **Existing Static Sites**: Need editing without architectural changes
+2. **Budget-Conscious Developers**: Need CMS features without enterprise costs
+3. **Framework-Agnostic Teams**: Want editing that works with any tech stack
+4. **Rapid Integration**: Need editing capabilities added in minutes, not days
+5. **Element-Level Editing**: Granular control over specific content elements
+
+---
+
+## Market Positioning: "The Tailwind of CMS"
+
+### Philosophy Parallel
+
+**Tailwind CSS Approach**:
+- Utility-first classes: `class="text-lg font-bold"`
+- Build-time optimization (PurgeCSS)
+- Framework agnostic
+- Developer workflow integration
+- Zero runtime overhead
+
+**Insertr CMS Approach**:
+- Content-first classes: `class="insertr"`
+- Build-time enhancement (content injection)
+- Framework agnostic
+- Developer workflow integration
+- Zero runtime overhead for visitors
+
+### Shared Principles
+
+#### 1. Zero Configuration Philosophy
+**Tailwind**: No CSS files, everything in HTML
+**Insertr**: No schema files, everything in HTML markup
+
+#### 2. Build-Time Optimization
+**Tailwind**: Unused styles purged at build time
+**Insertr**: Content injected and editor bundled at build time
+
+#### 3. Developer Experience Focus
+**Tailwind**: Stay in markup, don't context switch to CSS files
+**Insertr**: Stay in markup, don't context switch to CMS admin panels
+
+#### 4. Framework Agnostic
+**Tailwind**: Works with React, Vue, vanilla HTML, etc.
+**Insertr**: Works with Hugo, Next.js, Jekyll, etc.
+
+### Value Propositions
+
+#### For Developers:
+- **"Rapidly add editing to any website without ever leaving your markup"**
+- 5-minute setup vs days of CMS configuration
+- Works with existing design systems and frameworks
+- No architectural changes required
+
+#### For Content Editors:
+- Edit content directly on the live site
+- No forms, no admin panels - just click and edit
+- See changes exactly as visitors will
+
+#### For Agencies:
+- Turn any static site into an editable website for clients
+- No CMS migration needed - enhance existing sites
+- Client-friendly editing without developer complexity
+
+---
+
+## Technical Implementation
+
+### Auto-Generated Content IDs
+
+**Problem**: Manual `data-content-id` adds friction
+**Solution**: Automatic ID generation at build time
+
+**Developer Writes**:
+```html
+<h1 class="insertr">Welcome to Our Site</h1>
+<p class="insertr">This is editable content</p>
+```
+
+**Enhancement CLI Generates**:
+```html
+<h1 class="insertr" data-content-id="hero-welcome-title">
+  Latest Title From Database
+</h1>
+<p class="insertr" data-content-id="hero-description">
+  Latest Description From Database
+</p>
+```
+
+### Smart Loading for Performance
+
+**For Regular Visitors (99% of traffic)**:
+- Zero editor assets loaded
+- Pure static HTML performance
+- Tiny auth check (~1KB)
+
+**For Authenticated Editors**:
+- Rich editing UI loads on demand
+- Full feature set available
+- Real-time editing experience
+
+```javascript
+// Only load editor for authenticated users
+if (await insertr.isAuthenticated()) {
+  await insertr.loadEditor();
+  insertr.activateEditing();
+}
+// Otherwise: zero overhead
+```
+
+### Content Storage Architecture
+
+**Simple Database Model**:
+```sql
+CREATE TABLE content (
+  id SERIAL PRIMARY KEY,
+  content_id VARCHAR(255) UNIQUE NOT NULL,
+  site_id VARCHAR(255) NOT NULL,
+  value TEXT NOT NULL,
+  type VARCHAR(50) NOT NULL DEFAULT 'text',
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+**No File Mapping Required**:
+- Direct content_id → value lookup
+- No configuration files needed
+- Framework agnostic storage
+- Simple API: GET/PUT `/api/content/:id`
+
+---
+
+## Strategic Recommendations
+
+### 1. Market Positioning: "The Tailwind of CMS"
+
+**Target Personas**:
+- Full-stack developers building client sites
+- Frontend developers adding editing to existing sites
+- Agencies needing client-friendly editing solutions
+- Budget-conscious teams avoiding enterprise CMS costs
+
+**Core Message**: "Zero configuration content editing for any static site"
+
+### 2. Technical Architecture: HTML Enhancement Service
+
+**Core Components**:
+
+1. **Enhancement CLI**: 
+   - Parse HTML and identify editable elements
+   - Fetch latest content from database
+   - Inject content and editing capabilities
+   - Generate optimized bundles
+
+2. **Content Storage API**:
+   - Simple REST API for content CRUD
+   - Database-backed (PostgreSQL/SQLite)
+   - Multi-site content isolation
+   - Authentication integration
+
+3. **Smart Loading System**:
+   - Conditional editor asset loading
+   - Zero overhead for regular visitors
+   - Rich editing experience for authenticated users
+
+### 3. Differentiation Strategy
+
+#### Against CloudCannon:
+- **Simplicity**: `class="insertr"` vs complex component schemas
+- **Setup Time**: 5 minutes vs days of configuration
+- **Pricing**: Developer-friendly vs enterprise focus
+- **Flexibility**: Works with any design vs rigid components
+
+#### Against TinaCMS:
+- **Framework Agnostic**: Any SSG vs React/Next.js focus
+- **Zero Config**: Auto-generated IDs vs schema requirements
+- **Lightweight**: Focused enhancement vs full platform
+
+#### Against Decap CMS:
+- **Better UX**: Rich in-place editing vs basic forms
+- **Smart Rebuilds**: Batched updates vs every commit
+- **Active Development**: Modern architecture vs maintenance mode
+
+### 4. Implementation Roadmap
+
+#### Phase 3a: Enhancement Engine (4-6 weeks)
+- CLI tool for HTML parsing and content injection
+- Auto-generated content ID system
+- Database-backed content storage API
+- Smart asset loading implementation
+
+#### Phase 3b: Integration Examples (2-3 weeks)
+- GitHub Actions integration
+- Hugo/Jekyll/Next.js examples
+- Netlify/Vercel deployment guides
+- Performance optimization documentation
+
+#### Phase 3c: Developer Experience (3-4 weeks)
+- Comprehensive documentation
+- Interactive setup guides
+- Video tutorials and examples
+- Community building initiatives
+
+### 5. Success Metrics
+
+**Developer Adoption**:
+- Setup time: **< 5 minutes** (vs hours/days for competitors)
+- Performance impact: **0% for visitors** (pure static delivery)
+- Integration complexity: **Single CLI command**
+
+**User Experience**:
+- Edit-to-live time: **2-5 minutes** (build-dependent but acceptable)
+- Learning curve: **< 5 minutes** for content editors
+- Editor loading time: **< 2 seconds** for authenticated users
+
+### 6. Go-to-Market Strategy
+
+#### Developer-First Approach:
+1. **Open Source Core**: Build community credibility
+2. **Exceptional Documentation**: Focus on developer experience
+3. **Framework Integrations**: Support popular SSGs out of the box
+4. **Community Building**: Developer advocates, tutorials, examples
+
+#### Pricing Strategy:
+```
+Free Tier:      Open source, self-hosted, unlimited sites
+Hosted Tier:    $9/month, hosted API, basic features  
+Pro Tier:       $29/month, advanced features, priority support
+Agency Tier:    $99/month, multi-site management, white-label
+```
+
+---
+
+## Conclusion
+
+The strategic pivot to an "HTML Enhancement" approach positions Insertr uniquely in the CMS market. By embracing the "Tailwind philosophy" of utility-first, build-time optimization, and zero configuration, we can capture the under-served segment of developers who want powerful editing capabilities without architectural complexity.
+
+Key advantages of this approach:
+
+1. **Simplicity**: Eliminates file mapping and Git workflow complexity
+2. **Performance**: Zero runtime overhead for visitors, static site benefits maintained
+3. **Flexibility**: Works with any static site generator or HTML output
+4. **Developer Experience**: 5-minute setup vs days of traditional CMS configuration
+5. **Market Differentiation**: Unique positioning against component-heavy competitors
+
+The modular architecture developed in earlier phases provides the perfect foundation for this enhancement-service approach. By focusing on being the best possible editing experience that works with any content system, rather than trying to solve the entire CMS workflow, Insertr can achieve sustainable growth in the developer tools market.
+
+This "editing as a service" model represents the future of content management for static sites - lightweight, performant, and developer-friendly.