opentwig 1.1.0 → 1.1.2

package/AGENTS.md

@@ -7,69 +7,67 @@ This file provides guidelines for agentic coding assistants working on the OpenT
 ```bash
 # Run the CLI tool
 npm start
-# or: node src/index.js
 
-# CLI options
-npm start -- --help           # Show help information
-npm start -- --init           # Create sample config.json
-npm start -- --validate-config  # Validate config.json
-npm start -- --live            # Start live preview with config editor
+# Run a single test file
+npm test -- src/utils/parseArgs.test.js
+
+# Run tests matching a pattern
+npm test -- -t "should validate"
 
-# Test Open Graph image generation
-npm run test-og
+# Run tests once (CI mode)
+npm run test:run
 
-# Run automated tests (Vitest)
-npm test                    # Run tests in watch mode
-npm run test:run            # Run tests once
-npm run test:coverage       # Run tests with coverage report
+# Run tests with coverage
+npm run test:coverage
 
 # Start live preview mode
 npm run live
+
+# CLI options
+npm start -- --help
+npm start -- --init
 ```
 
 ## Project Overview
 
-OpenTwig is a Node.js CLI tool that generates static "link in bio" pages. It uses CommonJS modules and generates HTML, CSS, QR codes, and Open Graph images from a JSON configuration file.
+OpenTwig is a Node.js CLI tool that generates static "link in bio" pages. Uses CommonJS modules. Generates HTML, CSS, QR codes, and Open Graph images from JSON config.
 
-**Core technologies:** Node.js (v14+), CommonJS, PostCSS, Sharp, qrcode, html-minifier-terser, Express, WebSocket, Chokidar
+**Core technologies:** Node.js (v14+), CommonJS, PostCSS, Sharp, Vitest
 
 ## Code Style Guidelines
 
 ### Module System
 - **Use CommonJS exclusively** - no ES6 imports/exports
-- Import: `const moduleName = require('./path/to/module');`
+- Import: `const module = require('./path/to/module');`
 - Export: `module.exports = functionName;` or `module.exports = { name, value };`
-- Main entry point includes shebang: `#! /usr/bin/env node`
+- Main entry point includes shebang: `#! /usr/bin/env node` and `'use strict';`
 
 ### File Organization
 - **Single function per file** preferred in `src/utils/`
-- Use descriptive filenames in camelCase (e.g., `buildPage.js`, `generateQR.js`)
-- Theme structure: `theme/{themeName}/index.js`, `style.css`, `components/`
+- Use descriptive filenames in camelCase (e.g., `buildPage.js`)
 - Utilities in `src/utils/`, constants in `src/constants.js`
+- Theme structure: `theme/{themeName}/index.js`, `style.css`, `components/`
 
 ### Naming Conventions
 - **Variables/Functions**: camelCase (`const buildPage = async (config) => {}`)
 - **Constants**: UPPER_SNAKE_CASE (`const OUTPUT_FILES = { HTML: 'index.html' }`)
 - **Files**: camelCase for JS files (e.g., `loadConfig.js`)
-- **Destructured params**: Use descriptive names (`function({title, url, name})`)
 
 ### Code Patterns
 
 **Function exports:**
 ```javascript
-// Pattern: Immediately export a function
 module.exports = async function(config) {
     // implementation
 };
 ```
 
-**Async/await:**
+**Async/await with error handling:**
 ```javascript
 const buildPage = async (config) => {
     try {
         const theme = loadTheme(config);
-        const html = await generateHTML(config, theme);
-        return { html, theme };
+        return { html: await generateHTML(config, theme), theme };
     } catch (error) {
         throw new Error(`Failed to build page: ${error.message}`);
     }
@@ -91,29 +89,18 @@ module.exports = function({title, name}) {
 - Always use try-catch for async functions
 - Log errors with `console.error()`
 - Use `process.exit(1)` on fatal errors, `process.exit(0)` on success
-- Prefix error messages with context (e.g., `ERROR_PREFIX`)
-- Centralize error messages in `src/constants.js`
-
-```javascript
-try {
-    const result = await someAsyncOperation();
-    return result;
-} catch (error) {
-    throw new Error(`Operation failed: ${error.message}`);
-}
-```
+- Prefix error messages with context from `src/constants.js`
 
 ### Security
 - Always escape HTML output using `escapeHTML()` utility
-- Always escape XML for OG images using `escapeXml()`
+- Always escape XML for OG images using `escapeXml()` utility
 - Validate config fields in `configDefaults.js`
 - Sanitize all user-generated content
 
 ### Documentation
 - Add JSDoc comments for functions with @param and @returns
 - Add module-level docstrings describing purpose
-- Comment non-obvious logic
-- Example:
+
 ```javascript
 /**
  * Load theme configuration from theme directory
@@ -137,17 +124,6 @@ Centralize all constants in `src/constants.js`:
 - CLI options
 - Messages (ERROR_PREFIX, SUCCESS_PREFIX, etc.)
 - Default values
-- Configuration validation requirements
-
-### Component Pattern (Themes)
-Theme components in `theme/*/components/` export functions:
-```javascript
-module.exports = function({link}) {
-    return `<a href="${link.url}" target="_blank" rel="noopener">
-        <span>${link.title}</span>
-    </a>`;
-};
-```
 
 ### File Paths
 - Use `path.join()` for path construction
@@ -155,169 +131,42 @@ module.exports = function({link}) {
 - Use `process.cwd()` for current working directory
 - Check file existence with `fs.existsSync()` before operations
 
+## Testing Guidelines
+
+Tests use Vitest with ESM imports for test utilities and CommonJS require for modules:
+
+```javascript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+describe('functionName', () => {
+    it('should do something', () => {
+        const module = require('./module');
+        expect(result).toBe(expected);
+    });
+});
+```
+
 ## Key Files Reference
 
-- `src/index.js` - Main CLI entry point with argument parsing
-- `src/constants.js` - Centralized constants (including LIVE_MODE settings)
-- `src/utils/loadConfig.js` - Load and validate config.json
-- `src/utils/buildPage.js` - Orchestrate page generation
-- `src/utils/generateHTML.js` - HTML generation with minification
-- `src/utils/processCSS.js` - CSS processing with PostCSS
-- `src/utils/generateOGImage.js` - Open Graph image generation
-- `src/utils/generateQR.js` - QR code generation
-- `src/utils/saveFiles.js` - Save all output files to dist/
-- `src/utils/configDefaults.js` - Default values and validation
-- `src/utils/startLiveServer.js` - Live preview server (Express + WebSocket)
-- `src/utils/websocketServer.js` - WebSocket connection management
-- `src/utils/setupWatcher.js` - Config file change watcher
-- `src/live-ui/index.html` - Live editor main page
-- `src/live-ui/styles.css` - Live editor styles
-- `src/live-ui/preview.js` - Preview iframe management
-- `src/live-ui/editor.js` - Config editor logic
-- `src/live-ui/sidebar.js` - Sidebar components and form rendering
-- `theme/*/index.js` - Theme-specific HTML templates
-- `validateConfig.js` - Config validation utility
+- `src/index.js` - Main CLI entry point
+- `src/constants.js` - Centralized constants
+- `src/utils/` - Utility functions (one function per file)
+- `theme/` - Theme templates
+- `src/live-ui/` - Live editor UI
 
 ## Output Files
 
-All generated files go to `dist/` directory:
+All generated files go to `dist/`:
 - `index.html` - Main page
 - `style.css` - Processed CSS
-- `avatar.{ext}` - User avatar (if configured)
-- `og-image.jpg` - Open Graph preview image
+- `avatar.{ext}` - User avatar
+- `og-image.jpg` - Open Graph image
 - `qr.svg` - QR code
 
-## Live Mode Architecture
-
-### Overview
-Live mode (`--live` flag) provides an interactive development environment with real-time preview and configuration editing.
-
-### Components
-
-**Backend (Node.js):**
-- `startLiveServer.js` - Express server with WebSocket support
-  - HTTP endpoints: `/api/config`, `/api/themes`, `/api/avatar`, `/api/validate`
-  - Static file serving for `dist/` and `src/live-ui/`
-  - File upload handling (multer)
-- `websocketServer.js` - WebSocket server for real-time updates
-  - Broadcast events: `reload`, `config-update`, `theme-change`
-  - Client connection management
-- `setupWatcher.js` - Config file watcher
-  - Chokidar-based file watching
-  - Debounced change detection
-  - Auto rebuild on config changes
-
-**Frontend (Vanilla JS):**
-- `index.html` - Main editor page (Preview on left, Sidebar on right)
-- `preview.js` - Preview iframe management and WebSocket client
-- `editor.js` - Config API communication and auto-save
-- `sidebar.js` - Dynamic form generation and event handling
-
-### Features
-
-**Editor Features:**
-- Theme selection (default, dark, minimal, colorful)
-- Profile editing (URL, name, bio, avatar upload)
-- Links management (add, edit, delete, reorder)
-- Footer links management (URL or modal content)
-- Share settings configuration
-- Advanced settings (minify CSS)
-- Auto-save with debounce (500ms)
-- Export config as JSON
-
-**Real-time Updates:**
-- Config changes → WebSocket broadcast → Preview reload
-- File watcher → Rebuild → WebSocket broadcast
-- Avatar upload → Save → Rebuild → Preview update
-
-### Layout
-
-```
-┌─────────────────────────────────────────────┐
-│  Header: OpenTwig Live Editor  [Save][Export] │
-├──────────────────────────────┬──────────────┤
-│                              │              │
-│      Preview Iframe          │   Sidebar    │
-│  (dist/index.html embedded) │              │
-│                              │  - Theme     │
-│                              │  - Profile   │
-│                              │  - Links     │
-│                              │  - Footer    │
-│                              │  - Share     │
-│                              │  - Advanced  │
-│                              │              │
-├──────────────────────────────┴──────────────┤
-│  Status: Connected | Auto-save: ON         │
-└─────────────────────────────────────────────┘
-```
-
-### WebSocket Events
-
-**Server → Client:**
-```json
-{
-  "type": "reload"
-}
-
-{
-  "type": "config-update",
-  "config": { ... }
-}
-
-{
-  "type": "theme-change",
-  "theme": "dark"
-}
-```
-
-**API Endpoints:**
-
-**GET /api/config**
-- Returns current config from config.json
-- Creates sample config if not exists
-
-**POST /api/config**
-- Accepts config JSON
-- Validates and saves to config.json
-- Triggers rebuild and WebSocket broadcast
-
-**POST /api/avatar**
-- Accepts multipart form data with avatar file
-- Saves to working directory
-- Returns file path
-
-**GET /api/themes**
-- Returns array of available theme names
-
-**GET /api/validate?config=...**
-- Validates config JSON
-- Returns errors and warnings
-
-**GET /api/status**
-- Returns server status (connected clients, config path, etc.)
-
-## Testing Approach
-
-The project uses Vitest for automated testing:
-1. Run `npm test` to run tests in watch mode
-2. Run `npm run test:run` to run tests once
-3. Run `npm run test:coverage` to run tests with coverage report
-
-For manual testing:
-1. Create a config.json using `npm start -- --init`
-2. Run `npm start` to generate the page
-3. Verify `dist/` output files are generated correctly
-4. Test all themes by modifying config.json
-5. Test edge cases: missing avatar, empty config, long text
-6. Verify HTML is valid (open in browser)
-7. Check CSS renders correctly
-8. Confirm images are processed properly
-
 ## When Making Changes
 
 1. **Always read the file first** - Use the Read tool before editing
 2. **Follow existing patterns** - Mimic code style and structure
-3. **Test thoroughly** - Manual testing after changes
+3. **Test thoroughly** - Run `npm run test:run` after changes
 4. **Add JSDoc comments** - Document new functions
-5. **Update constants** if needed - Add new constants to `src/constants.js`
-6. **Keep it simple** - One function per file, focused responsibilities
+5. **Keep it simple** - One function per file, focused responsibilities

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentwig",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "opentwig 🌿 is an open source link in bio page generator.",
   "main": "src/index.js",
   "bin": {
@@ -11,7 +11,6 @@
     "test": "vitest",
     "test:run": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "test-og": "node test-og.js",
     "live": "node src/index.js --live"
   },
   "devDependencies": {
@@ -62,4 +61,4 @@
   "browserslist": [
     "ie 9"
   ]
-}
+}

package/src/live-ui/editor.js

@@ -166,6 +166,7 @@ window.configEditor = {
     loadConfig,
     saveConfig,
     autoSave,
+    validateField,
     currentConfig: () => currentConfig,
     updateConfig: (newConfig) => {
         currentConfig = newConfig;

package/src/live-ui/index.html

@@ -0,0 +1,94 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>OpenTwig Live Editor</title>
+    <link rel="stylesheet" href="/live-ui/styles.css">
+</head>
+<body>
+    <div class="app-container">
+        <header class="app-header">
+            <div class="header-left">
+                <h1>🌿 OpenTwig Live Editor</h1>
+                <span class="status-indicator" id="statusIndicator">
+                    <span class="status-dot"></span>
+                    <span class="status-text">Connecting...</span>
+                </span>
+            </div>
+            <div class="header-right">
+                <button class="btn btn-primary" id="saveBtn">
+                    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                        <path d="M19 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11l5 5v11a2 2 0 0 1-2 2z"></path>
+                        <polyline points="17 21 17 13 7 13 7 21"></polyline>
+                        <polyline points="7 3 7 8 15 8"></polyline>
+                    </svg>
+                    Save
+                </button>
+                <button class="btn btn-secondary" id="exportBtn">
+                    <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                        <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"></path>
+                        <polyline points="7 10 12 15 17 10"></polyline>
+                        <line x1="12" y1="15" x2="12" y2="3"></line>
+                    </svg>
+                    Export
+                </button>
+            </div>
+        </header>
+
+        <div class="main-content">
+            <div class="preview-container">
+                <div class="preview-toolbar">
+                    <span class="preview-title">Preview</span>
+                    <button class="refresh-btn" id="refreshBtn" title="Refresh preview">
+                        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                            <polyline points="23 4 23 10 17 10"></polyline>
+                            <path d="M20.49 15a9 9 0 1 1-2.12-9.36L23 10"></path>
+                        </svg>
+                    </button>
+                </div>
+                <div class="preview-frame">
+                    <iframe id="previewFrame" src="/index.html" title="Preview"></iframe>
+                </div>
+            </div>
+
+            <aside class="sidebar">
+                <div class="sidebar-header">
+                    <h2>Configuration</h2>
+                    <button class="toggle-sidebar" id="toggleSidebar" title="Toggle sidebar">
+                        <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                            <line x1="18" y1="6" x2="6" y2="18"></line>
+                            <line x1="6" y1="6" x2="18" y2="18"></line>
+                        </svg>
+                    </button>
+                </div>
+
+                <div class="sidebar-content">
+                    <div class="config-section" id="configForm">
+                        <!-- Dynamic form content will be injected here -->
+                    </div>
+                </div>
+
+                <div class="sidebar-footer">
+                    <div class="auto-save-toggle">
+                        <label class="toggle-switch">
+                            <input type="checkbox" id="autoSave" checked>
+                            <span class="slider"></span>
+                        </label>
+                        <span>Auto-save</span>
+                    </div>
+                    <div class="last-saved">
+                        Last saved: <span id="lastSaved">Never</span>
+                    </div>
+                </div>
+            </aside>
+        </div>
+
+        <div class="notification-container" id="notificationContainer"></div>
+    </div>
+
+    <script src="/live-ui/preview.js"></script>
+    <script src="/live-ui/editor.js"></script>
+    <script src="/live-ui/sidebar.js"></script>
+</body>
+</html>

package/src/live-ui/sidebar.js

@@ -383,6 +383,8 @@ const renderShareSection = (container, config) => {
     
     const shareUrlGroup = createFormGroup('Share URL', '', config.share.url, 'text', (value) => {
         config.share.url = value;
+        // Sync with main URL so QR code updates correctly
+        config.url = value;
         window.configEditor.updateConfig(config);
         window.configEditor.autoSave(config);
         return [];