Files

Joakim ca3df47451 feat: complete code cleanup and create feature parity plan

Major Architecture Improvements:
- Separate JavaScript library (lib/) with proper build system
- Go CLI with embedded library using go:embed
- Hot reload development with Air integration
- Library + CLI build pipeline with npm run build

Code Cleanup:
- Remove obsolete assets (insertr-cli/assets/editor/)
- Clean up package.json metadata and dependencies
- Update .gitignore for new architecture
- Remove unused 'marked' dependency

New Documentation:
- Add comprehensive TODO.md with feature gap analysis
- Document critical gaps between prototype and current library
- Create phased implementation plan for feature parity
- Update DEVELOPMENT.md with hot reload workflow
- Add LIBRARY.md documenting new architecture

Hot Reload System:
- Air watches both Go CLI and JavaScript library
- Library changes trigger: rebuild → copy → CLI rebuild → serve
- Seamless development experience across full stack

Next Steps:
- Current library is basic proof-of-concept (prompt() editing)
- Archived prototype has production-ready features
- Phase 1 focuses on professional forms and authentication
- Phase 2 adds validation and content persistence

2025-09-03 19:11:54 +02:00

4.2 KiB

Raw Blame History

Insertr Library Architecture

Overview

Insertr now uses a proper separation between the JavaScript library and Go CLI, following the "Tailwind of CMS" philosophy where the library can be developed independently and embedded into the CLI at build time.

Project Structure

insertr/
├── lib/                          # Independent JavaScript library
│   ├── src/
│   │   ├── core/
│   │   │   ├── insertr.js       # Main library core
│   │   │   ├── editor.js        # Visual editing functionality  
│   │   │   └── api-client.js    # Content API client
│   │   └── index.js             # Library entry point
│   ├── dist/
│   │   ├── insertr.js           # Built library (dev)
│   │   └── insertr.min.js       # Built library (production)
│   ├── package.json
│   └── rollup.config.js         # Build configuration
├── insertr-cli/                  # Go CLI with embedded library
│   ├── pkg/content/
│   │   ├── assets/              # Embedded library files
│   │   │   ├── insertr.js       # From lib/dist/
│   │   │   └── insertr.min.js   # From lib/dist/
│   │   ├── library.go           # Go embed declarations
│   │   ├── injector.go          # HTML injection logic
│   │   └── ...
│   └── insertr                  # Built CLI executable
└── scripts/
    └── build.js                 # Integrated build script

Build Process

1. Library Development (`lib/`)

cd lib
npm install
npm run build    # Creates dist/insertr.js and dist/insertr.min.js
npm run watch    # Development mode with file watching

2. CLI Integration (`insertr-cli/`)

The CLI uses Go's //go:embed directive to embed the built library:

//go:embed assets/insertr.min.js
var libraryMinJS string

//go:embed assets/insertr.js  
var libraryJS string

3. Integrated Build (Root)

npm run build    # Builds both library AND CLI with embedded assets

This script:

Builds the JavaScript library (lib/dist/)
Copies built assets to CLI (insertr-cli/pkg/content/assets/)
Builds Go CLI with embedded library

Library Features

Core Functionality (`src/core/insertr.js`)

Element discovery: findEnhancedElements()
Metadata extraction: getElementMetadata()
Element management: getAllElements()

Visual Editor (`src/core/editor.js`)

Hover effects and visual indicators
Click-to-edit functionality
Content update handling
Dynamic style injection

API Client (`src/core/api-client.js`)

RESTful content API communication
CRUD operations for content
Error handling and fallbacks

CLI Integration

Asset Embedding (`pkg/content/library.go`)

func GetLibraryScript(minified bool) string {
    if minified {
        return libraryMinJS  // Production: smaller file size
    }
    return libraryJS         // Development: readable code
}

HTML Injection (`pkg/content/injector.go`)

func (i *Injector) InjectEditorAssets(doc *html.Node, isDevelopment bool, libraryScript string) {
    // Injects the embedded library as inline <script> tag
}

Development Workflow

Library Development

cd lib
npm run watch    # Auto-rebuild on changes

CLI Development

cd insertr-cli
go build -o insertr
./insertr enhance ../demo-site/

Full Integration Testing

npm run build    # Builds library + CLI
cd insertr-cli && ./insertr enhance ../demo-site/

Benefits

Independent Development: Library can be developed and tested separately
Version Control: CLI embeds specific library version at build time
Zero Dependencies: Enhanced HTML contains everything needed to run
CDN Ready: Library can be served from CDN in production
Development Friendly: Unminified version for debugging

Future Enhancements

CDN Integration: Support for <script src="https://cdn.insertr.dev/v1.0.0/insertr.min.js">
Library Hot Reload: Auto-rebuild CLI when library changes
Version Sync: Automated version bumping across library and CLI
Production Optimization: Tree-shaking and custom builds

4.2 KiB Raw Blame History