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
This commit is contained in:
138
LIBRARY.md
Normal file
138
LIBRARY.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# 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/`)
|
||||
```bash
|
||||
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
|
||||
//go:embed assets/insertr.min.js
|
||||
var libraryMinJS string
|
||||
|
||||
//go:embed assets/insertr.js
|
||||
var libraryJS string
|
||||
```
|
||||
|
||||
### 3. Integrated Build (Root)
|
||||
```bash
|
||||
npm run build # Builds both library AND CLI with embedded assets
|
||||
```
|
||||
|
||||
This script:
|
||||
1. Builds the JavaScript library (`lib/dist/`)
|
||||
2. Copies built assets to CLI (`insertr-cli/pkg/content/assets/`)
|
||||
3. 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`)
|
||||
```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`)
|
||||
```go
|
||||
func (i *Injector) InjectEditorAssets(doc *html.Node, isDevelopment bool, libraryScript string) {
|
||||
// Injects the embedded library as inline <script> tag
|
||||
}
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Library Development
|
||||
```bash
|
||||
cd lib
|
||||
npm run watch # Auto-rebuild on changes
|
||||
```
|
||||
|
||||
### CLI Development
|
||||
```bash
|
||||
cd insertr-cli
|
||||
go build -o insertr
|
||||
./insertr enhance ../demo-site/
|
||||
```
|
||||
|
||||
### Full Integration Testing
|
||||
```bash
|
||||
npm run build # Builds library + CLI
|
||||
cd insertr-cli && ./insertr enhance ../demo-site/
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Independent Development**: Library can be developed and tested separately
|
||||
2. **Version Control**: CLI embeds specific library version at build time
|
||||
3. **Zero Dependencies**: Enhanced HTML contains everything needed to run
|
||||
4. **CDN Ready**: Library can be served from CDN in production
|
||||
5. **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
|
||||
Reference in New Issue
Block a user