From ca3df47451933c12894c99a34205380e2476720e Mon Sep 17 00:00:00 2001 From: Joakim Date: Wed, 3 Sep 2025 19:11:54 +0200 Subject: [PATCH] feat: complete code cleanup and create feature parity plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .gitignore | 6 +- CLEANUP_SUMMARY.md | 76 ++++ DEVELOPMENT.md | 133 ++++-- LIBRARY.md | 138 ++++++ README.md | 14 +- TODO.md | 128 ++++++ insertr-cli/.air.toml | 8 +- insertr-cli/assets/editor/insertr-editor.js | 85 ---- insertr-cli/assets/lib/insertr.js | 197 +++++++++ insertr-cli/assets/lib/insertr.min.js | 1 + insertr-cli/pkg/content/assets/insertr.js | 197 +++++++++ insertr-cli/pkg/content/assets/insertr.min.js | 1 + insertr-cli/pkg/content/enhancer.go | 3 +- insertr-cli/pkg/content/injector.go | 14 +- insertr-cli/pkg/content/library.go | 26 ++ insertr-cli/scripts/rebuild-library.sh | 20 + lib/package-lock.json | 417 ++++++++++++++++++ lib/package.json | 30 ++ lib/rollup.config.js | 30 ++ lib/src/core/api-client.js | 57 +++ lib/src/core/editor.js | 110 +++++ lib/src/core/insertr.js | 32 ++ lib/src/index.js | 49 ++ package-lock.json | 15 - package.json | 20 +- scripts/build.js | 58 +++ test-hot-reload.sh | 46 ++ 27 files changed, 1747 insertions(+), 164 deletions(-) create mode 100644 CLEANUP_SUMMARY.md create mode 100644 LIBRARY.md create mode 100644 TODO.md delete mode 100644 insertr-cli/assets/editor/insertr-editor.js create mode 100644 insertr-cli/assets/lib/insertr.js create mode 100644 insertr-cli/assets/lib/insertr.min.js create mode 100644 insertr-cli/pkg/content/assets/insertr.js create mode 100644 insertr-cli/pkg/content/assets/insertr.min.js create mode 100644 insertr-cli/pkg/content/library.go create mode 100755 insertr-cli/scripts/rebuild-library.sh create mode 100644 lib/package-lock.json create mode 100644 lib/package.json create mode 100644 lib/rollup.config.js create mode 100644 lib/src/core/api-client.js create mode 100644 lib/src/core/editor.js create mode 100644 lib/src/core/insertr.js create mode 100644 lib/src/index.js create mode 100755 scripts/build.js create mode 100755 test-hot-reload.sh diff --git a/.gitignore b/.gitignore index f739229..66b900b 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,9 @@ yarn-error.log* # Build outputs dist/ build/ +lib/dist/ +insertr-cli/insertr +insertr-cli/tmp/ # Environment files .env @@ -49,7 +52,7 @@ temp/ # Optional REPL history .node_repl_history -# Go specific (for future backend) +# Go specific *.exe *.exe~ *.dll @@ -59,6 +62,7 @@ temp/ *.out go.work vendor/ +insertr-cli/build-errors.log # Database files *.db diff --git a/CLEANUP_SUMMARY.md b/CLEANUP_SUMMARY.md new file mode 100644 index 0000000..7086826 --- /dev/null +++ b/CLEANUP_SUMMARY.md @@ -0,0 +1,76 @@ +# Code Cleanup Summary + +## Artifacts Removed from Architecture Pivot + +### ๐Ÿ—‘๏ธ **Obsolete Assets Removed** +- `insertr-cli/assets/editor/insertr-editor.js` - Legacy inline editor script +- `insertr-cli/assets/editor/` directory - No longer needed +- Unused `marked` npm dependency from root package.json + +### ๐Ÿงน **Root Package.json Cleanup** +**Before:** +```json +{ + "description": "Edit-in-place CMS for client websites - simple integration with class-based content editing", + "main": "demo-site/insertr/insertr.js", + "keywords": ["cms", "edit-in-place", "inline-editing", "client-websites", "go", "htmx", "alpine"], + "dependencies": { + "marked": "^16.2.1" + } +} +``` + +**After:** +```json +{ + "description": "The Tailwind of CMS - Zero-configuration content editing for any static site", + "main": "lib/dist/insertr.js", + "keywords": ["cms", "headless-cms", "static-site-generator", "build-time-enhancement", "zero-config", "go", "javascript"], + "dependencies": {} +} +``` + +### โœ… **Legacy Code Preserved (Intentionally)** +- `demo-site/archive/` - Contains original prototype for reference +- `scripts/dev.js` - Still useful for testing original prototype +- Legacy npm scripts (`dev:*`) - Kept for prototype development +- `demo-site/README.md` - Accurately describes prototype functionality + +### ๐Ÿ”ง **Enhanced .gitignore** +Added new build artifacts: +```gitignore +# Build outputs +lib/dist/ # Library build output +insertr-cli/insertr # CLI executable +insertr-cli/tmp/ # Air temporary files +insertr-cli/build-errors.log # Air error logs +``` + +### ๐ŸŽฏ **What Was NOT Removed** +- **Archive directory**: `demo-site/archive/` kept for reference +- **Development scripts**: Legacy scripts still work for prototype testing +- **Documentation references**: Accurate historical context preserved +- **Go embed assets**: `insertr-cli/pkg/content/assets/` must stay for embedding + +## Validation + +### โœ… **Build System Verified** +```bash +npm run build # โœ… Works +cd insertr-cli && air # โœ… Hot reload works +./insertr enhance # โœ… CLI works with embedded library +``` + +### โœ… **Architecture Clean** +- No dead code or unused imports in Go +- No obsolete script references +- Clean dependency tree (1 package removed) +- Updated project metadata reflects current architecture + +### ๐ŸŽฏ **Result** +The codebase now cleanly separates: +1. **Current Architecture**: `lib/` + `insertr-cli/` with proper embedding +2. **Legacy Prototype**: `demo-site/archive/` for reference +3. **Test Content**: `demo-site/` HTML files for enhancement testing + +No functionality was lost, and the transition from prototype to production architecture is complete. \ No newline at end of file diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 2ca702b..1b5b276 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -2,30 +2,52 @@ ## Quick Start +### Full-Stack Development (Recommended) 1. **Install dependencies**: ```bash - npm install + npm install # Root project dependencies + cd lib && npm install # Library dependencies ``` -2. **Start development server**: +2. **Start hot reload development**: ```bash - npm run dev + cd insertr-cli && air # Starts server with library hot reload ``` - This will start live-server on http://localhost:3000 and automatically open the demo site. + - Watches both Go CLI changes AND JavaScript library changes + - Automatically rebuilds library โ†’ CLI โ†’ serves enhanced content + - Visit http://localhost:3000 to see results -3. **Alternative commands**: - ```bash - npm run dev:about # Open about page directly - npm run serve # Alias for npm run dev - ``` +### Library-Only Development +```bash +cd lib && npm run watch # Just develop the JavaScript library +``` + +### Legacy Frontend Development +```bash +npm run dev # Legacy live-server (demo-site only) +``` ## Development Workflow -### Frontend Development (Current Phase) +### 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 main Insertr library -- **Styling**: `demo-site/insertr/insertr.css` - edit interface styles +- **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 @@ -36,9 +58,15 @@ ### 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` to modify core functionality -- **Styling**: Edit `demo-site/insertr/insertr.css` for UI changes +- **JavaScript**: Edit `demo-site/insertr/insertr.js` for prototype functionality - **Content**: Edit HTML files to test different content structures ### Adding New Features @@ -51,40 +79,67 @@ ``` insertr/ -โ”œโ”€โ”€ INITIAL.md # Project requirements and research โ”œโ”€โ”€ DEVELOPMENT.md # This file -โ”œโ”€โ”€ package.json # Node.js project configuration -โ”œโ”€โ”€ .gitignore # Git ignore rules +โ”œโ”€โ”€ LIBRARY.md # Library architecture documentation +โ”œโ”€โ”€ package.json # Root project configuration โ”‚ -โ”œโ”€โ”€ demo-site/ # Frontend prototype +โ”œโ”€โ”€ 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 -โ”‚ โ”œโ”€โ”€ README.md # Demo usage instructions -โ”‚ โ”‚ -โ”‚ โ”œโ”€โ”€ assets/ # Demo site assets -โ”‚ โ”‚ โ””โ”€โ”€ style.css # Demo site styling -โ”‚ โ”‚ -โ”‚ โ”œโ”€โ”€ insertr/ # Core Insertr library -โ”‚ โ”‚ โ”œโ”€โ”€ insertr.js # Main library file -โ”‚ โ”‚ โ”œโ”€โ”€ insertr.css # Edit interface styles -โ”‚ โ”‚ โ””โ”€โ”€ components/ # Future: reusable edit components -โ”‚ โ”‚ -โ”‚ โ””โ”€โ”€ mock-api/ # Backend planning -โ”‚ โ””โ”€โ”€ content.json # Sample data structure +โ”‚ โ””โ”€โ”€ assets/style.css # Demo site styling โ”‚ -โ””โ”€โ”€ backend/ # Future: Go backend - โ”œโ”€โ”€ main.go # Future: HTTP server - โ”œโ”€โ”€ api/ # Future: REST endpoints - โ””โ”€โ”€ storage/ # Future: file-based storage +โ””โ”€โ”€ scripts/ + โ””โ”€โ”€ build.js # Integrated build script ``` ## Development Scripts -- `npm run dev` - Start development server with live reload -- `npm run dev:about` - Start server opening about page -- `npm run build` - Future: Bundle library for distribution -- `npm run test` - Future: Run tests -- `npm run lint` - Future: Code linting +### 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 ` - Enhance static site +- `./insertr servedev ` - Development server with enhancement + +### Hot Reload Workflow +```bash +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 diff --git a/LIBRARY.md b/LIBRARY.md new file mode 100644 index 0000000..02d9c4e --- /dev/null +++ b/LIBRARY.md @@ -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