insertr/DEVELOPMENT.md

Insertr Development Guide

Quick Start

Full-Stack Development (Recommended)

1. Install dependencies:

   npm install                    # Root project dependencies
   cd lib && npm install         # Library dependencies
   

2. Start hot reload development:

   cd insertr-cli && air         # Starts server with library hot reload
   

   • Watches both Go CLI changes AND JavaScript library changes
   • Automatically rebuilds library → CLI → serves enhanced content
   • Visit http://localhost:3000 to see results

Library-Only Development

cd lib && npm run watch         # Just develop the JavaScript library

Legacy Frontend Development

npm run dev                     # Legacy live-server (demo-site only)

Development Workflow

Hot Reload Development (Current Phase)

🔥 NEW: Full-stack hot reload with Air integration!

• Library Source: lib/src/ - Independent JavaScript library
• CLI Integration: insertr-cli/ - Go CLI with embedded library
• Demo Site: demo-site/ - Test website for enhancement
• Automatic Rebuilds: Changes to JS library trigger full rebuild cycle

How Hot Reload Works:

1. Edit JavaScript in lib/src/
2. Air detects changes → Rebuilds library → Copies to CLI → Rebuilds CLI
3. Enhanced development server serves updated content
4. Manual browser refresh shows changes

Legacy Frontend Development

• Demo Site: demo-site/ contains the prototype website
• Core Library: demo-site/insertr/insertr.js - the old prototype library
• Mock API: demo-site/mock-api/content.json - sample backend data structure

Testing the Three User Types

1. Customer View: Open the site normally - clean, no edit interface
2. Client View: Click "Login as Client" then "Edit Mode: On" - see edit buttons
3. Developer View: Look at the HTML source to see simple integration

Making Changes

Modern Development (lib/ + insertr-cli/)

• Library Changes: Edit lib/src/**/*.js → Air automatically rebuilds everything
• CLI Changes: Edit Go files in insertr-cli/ → Air rebuilds and restarts server
• Demo Content: Edit demo-site/*.html → Air serves enhanced versions
• Hot Reload: Changes trigger full rebuild cycle (library → CLI → enhanced content)

Legacy Development (demo-site/)

• Live Reload: The server automatically refreshes when you save changes
• JavaScript: Edit demo-site/insertr/insertr.js for prototype functionality
• Content: Edit HTML files to test different content structures

Adding New Features

1. Content Types: Extend the createEditForm() method in insertr.js
2. UI Components: Add new CSS classes and corresponding JavaScript
3. Authentication: Modify the mock auth system in toggleAuthentication()

Project Structure

insertr/
├── DEVELOPMENT.md          # This file
├── LIBRARY.md             # Library architecture documentation  
├── package.json           # Root project configuration
│
├── lib/                   # 🆕 Independent JavaScript Library
│   ├── src/
│   │   ├── core/
│   │   │   ├── insertr.js    # Core library functionality
│   │   │   ├── editor.js     # Visual editing interface
│   │   │   └── api-client.js # Content API client
│   │   └── index.js          # Library entry point
│   ├── dist/
│   │   ├── insertr.js        # Built library (development)
│   │   └── insertr.min.js    # Built library (production)
│   ├── package.json          # Library dependencies
│   └── rollup.config.js      # Build configuration
│
├── insertr-cli/           # 🆕 Go CLI with Embedded Library
│   ├── pkg/content/
│   │   ├── assets/           # Embedded library files (auto-copied)
│   │   ├── library.go        # Go embed declarations  
│   │   ├── enhancer.go       # HTML enhancement orchestrator
│   │   ├── injector.go       # Content injection logic
│   │   └── ...
│   ├── scripts/
│   │   └── rebuild-library.sh # Air helper script
│   ├── .air.toml            # Hot reload configuration
│   └── insertr             # Built CLI executable
│
├── demo-site/             # Test website for enhancement
│   ├── index.html         # Demo homepage
│   ├── about.html         # Demo about page
│   └── assets/style.css   # Demo site styling
│
└── scripts/
    └── build.js           # Integrated build script

Development Scripts

Root Scripts

• npm run build - Build library + CLI with embedded assets
• npm run dev - Legacy live-server (demo-site only)

Library Scripts (cd lib/)

• npm run build - Build library to dist/
• npm run watch - Watch and rebuild library on changes

CLI Scripts (cd insertr-cli/)

• air - 🔥 Hot reload server (library + CLI + enhanced content)
• go build -o insertr - Manual CLI build
• ./insertr enhance <dir> - Enhance static site
• ./insertr servedev <dir> - Development server with enhancement

Hot Reload Workflow

cd insertr-cli && air    # Start hot reload development
# Edit lib/src/**/*.js   # Air detects → rebuilds → serves
# Edit cmd/**/*.go       # Air detects → rebuilds → serves  
# Edit ../demo-site/     # Air serves enhanced versions

Testing Different Scenarios

Content Types

• Simple Text: Logo, titles, short descriptions
• Rich Content: Paragraphs with markdown, lists, links
• Mixed Content: Cards with multiple editable sections

User Flows

1. First Visit: Customer sees clean site
2. Client Login: Authentication state changes
3. Edit Mode: Toggle editing interface
4. Content Editing: Click edit → modify → save
5. Multi-page: Test persistence across pages

Browser Testing

Test in different browsers to ensure compatibility:

• Chrome/Edge (Chromium)
• Firefox
• Safari (if on macOS)

Future Development Phases

Phase 2: Backend Integration

• Go HTTP server with REST API
• Real authentication with Authentik OAuth
• File-based content persistence
• Git version control

Phase 3: Production Features

• Multi-tenant support
• Admin dashboard
• Content validation
• Image upload
• Deployment automation

Contributing Guidelines

1. Make changes in small, focused commits
2. Test thoroughly across different content types
3. Update documentation when adding new features
4. Follow existing code style and patterns

Debugging Tips

JavaScript Console

• Open browser dev tools (F12)
• Check for errors in Console tab
• Use window.insertr to inspect library state

Local Storage

• View saved content: localStorage.getItem('insertr_content')
• Clear saved content: localStorage.clear()

Network Simulation

• The library simulates network delays and occasional failures
• Check browser Network tab to see mock API calls (when implemented)

Common Issues

Live Server Not Working

• Ensure port 3000 is available
• Try different port: live-server demo-site --port=3001

Changes Not Reflecting

• Hard refresh browser (Ctrl+F5 / Cmd+Shift+R)
• Check browser cache settings
• Verify file paths are correct

Edit Buttons Not Showing

• Check authentication state (click "Login as Client")
• Enable edit mode (click "Edit Mode: Off" → "Edit Mode: On")
• Verify elements have class="insertr" and data-content-id