opentwig 1.1.0 → 1.1.1

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.1",
   "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/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 [];

package/src/utils/favicon.js

@@ -0,0 +1,20 @@
+/**
+ * Leaf favicon SVG for OpenTwig
+ * Used across all themes
+ */
+
+const LEAF_FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#16a34a" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M11 20A7 7 0 0 1 9.8 6.1C15.5 5 17 4.48 19 2c1 2 2 4.18 2 8 0 5.5-4.78 10-10 10Z"/><path d="M2 21c0-3 1.85-5.36 5.08-6C9.5 14.52 12 13 13 12"/></svg>`;
+
+/**
+ * Get favicon as data URI for embedding in HTML
+ * @returns {string} Data URI for favicon
+ */
+function getFaviconDataURI() {
+    const base64 = Buffer.from(LEAF_FAVICON_SVG).toString('base64');
+    return `data:image/svg+xml;base64,${base64}`;
+}
+
+module.exports = {
+    LEAF_FAVICON_SVG,
+    getFaviconDataURI
+};

package/src/utils/loadConfig.js

@@ -11,7 +11,9 @@ module.exports = function() {
         process.exit(1);
     }
     
-    const config = require(configPath);
+    // Use fs.readFileSync instead of require to avoid caching issues
+    const configContent = fs.readFileSync(configPath, 'utf8');
+    const config = JSON.parse(configContent);
     
     // Apply default values to the loaded configuration
     return applyDefaults(config);

package/src/utils/setupWatcher.js

@@ -12,10 +12,10 @@ const setupWatcher = (configPath, wss, onConfigChange) => {
     let watcher = null;
     let isPaused = false;
     
-    const handleConfigChange = debounce(async (event, path) => {
+    const handleConfigChange = debounce(async (path) => {
         if (isPaused) return;
         
-        console.log(`Config file changed: ${event} ${path}`);
+        console.log(`Config file changed: ${path}`);
         
         try {
             if (onConfigChange) {

package/src/utils/startLiveServer.js

@@ -50,22 +50,22 @@ const startLiveServer = async (customPort) => {
         }
     });
     
-    app.post('/api/config', (req, res) => {
+    app.post('/api/config', async (req, res) => {
         try {
             const newConfig = req.body;
             currentConfig = applyDefaults(newConfig);
             
             fs.writeFileSync(configPath, JSON.stringify(currentConfig, null, 4));
             
-            buildPage(currentConfig).then(({ html, css, ogImage, qrImage }) => {
-                saveFiles(html, css, currentConfig.avatar, ogImage, qrImage);
-                wss.broadcastConfigUpdate(currentConfig);
-            }).catch(error => {
-                console.error('Error building page:', error);
-            });
+            const { html, css, ogImage, qrImage } = await buildPage(currentConfig);
+            saveFiles(html, css, currentConfig.avatar, ogImage, qrImage);
             
             res.json({ success: true, config: currentConfig });
+            
+            // Broadcast reload after files are saved
+            wss.broadcastReload();
         } catch (error) {
+            console.error('Error building page:', error);
             res.status(500).json({ error: error.message });
         }
     });
@@ -201,7 +201,10 @@ const startLiveServer = async (customPort) => {
     
     const watcher = setupWatcher(configPath, wss, async (changedPath) => {
         try {
-            currentConfig = loadConfig();
+            // Read config directly from file to avoid require cache issues
+            const configContent = fs.readFileSync(configPath, 'utf8');
+            const fileConfig = JSON.parse(configContent);
+            currentConfig = applyDefaults(fileConfig);
             await buildPage(currentConfig);
             console.log('Page rebuilt from config change');
         } catch (error) {

package/theme/default/index.js

@@ -5,6 +5,7 @@ const shareButtonComponent = require('./components/share-button');
 const qrComponent = require('./components/qr');
 const dialogComponent = require('./components/dialog');
 const escapeHTML = require('../../src/utils/escapeHTML');
+const { getFaviconDataURI } = require('../../src/utils/favicon');
 
 module.exports = function({title, url, name, content, avatar, links, footerLinks, share}) {
 
@@ -20,6 +21,7 @@ module.exports = function({title, url, name, content, avatar, links, footerLinks
   <meta property="og:description" content="${escapeHTML(content)}"/>
   <meta property="og:url" content="${escapeHTML(url)}"/>
   <meta property="og:image" content="${escapeHTML(url)}/og-image.jpg"/>
+  <link rel="icon" type="image/svg+xml" href="${getFaviconDataURI()}">
     </head>
     <body>
       <div class="app-bg">

package/vitest.config.js

@@ -1,11 +1,20 @@
-module.exports = {
-  test: {
-    environment: 'node',
-    include: ['**/*.test.js'],
-    coverage: {
-      provider: 'v8',
-      reporter: ['text', 'json'],
-      exclude: ['node_modules/', 'dist/', '**/*.test.js', 'test-og.js']
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: 'node',
+        include: ['tests/**/*.test.js'],
+        coverage: {
+            provider: 'v8',
+            reporter: ['text', 'json', 'html'],
+            exclude: [
+                'node_modules/',
+                'tests/',
+                'website/',
+                'theme/',
+                'dist/'
+            ]
+        }
     }
-  }
-};
+});

package/website/README.md

@@ -0,0 +1,42 @@
+# sv
+
+Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).
+
+## Creating a project
+
+If you're seeing this, you've probably already done this step. Congrats!
+
+```sh
+# create a new project
+npx sv create my-app
+```
+
+To recreate this project with the same configuration:
+
+```sh
+# recreate this project
+npx sv create --template minimal --types ts --add eslint tailwindcss="plugins:typography" sveltekit-adapter="adapter:static" --install npm website
+```
+
+## Developing
+
+Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+
+```sh
+npm run dev
+
+# or start the server and open the app in a new browser tab
+npm run dev -- --open
+```
+
+## Building
+
+To create a production version of your app:
+
+```sh
+npm run build
+```
+
+You can preview the production build with `npm run preview`.
+
+> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.

package/website/components.json

@@ -0,0 +1,16 @@
+{
+	"$schema": "https://shadcn-svelte.com/schema.json",
+	"tailwind": {
+		"css": "src/routes/layout.css",
+		"baseColor": "slate"
+	},
+	"aliases": {
+		"components": "$lib/components",
+		"utils": "$lib/utils",
+		"ui": "$lib/components/ui",
+		"hooks": "$lib/hooks",
+		"lib": "$lib"
+	},
+	"typescript": true,
+	"registry": "https://shadcn-svelte.com/registry"
+}

package/website/eslint.config.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { includeIgnoreFile } from '@eslint/compat';
+import js from '@eslint/js';
+import svelte from 'eslint-plugin-svelte';
+import { defineConfig } from 'eslint/config';
+import globals from 'globals';
+import ts from 'typescript-eslint';
+import svelteConfig from './svelte.config.js';
+
+const gitignorePath = path.resolve(import.meta.dirname, '.gitignore');
+
+export default defineConfig(
+	includeIgnoreFile(gitignorePath),
+	js.configs.recommended,
+	...ts.configs.recommended,
+	...svelte.configs.recommended,
+	{
+		languageOptions: { globals: { ...globals.browser, ...globals.node } },
+		rules: {
+			// typescript-eslint strongly recommend that you do not use the no-undef lint rule on TypeScript projects.
+			// see: https://typescript-eslint.io/troubleshooting/faqs/eslint/#i-get-errors-from-the-no-undef-rule-about-global-variables-not-being-defined-even-though-there-are-no-typescript-errors
+			"no-undef": 'off'
+		}
+	},
+	{
+		files: ['**/*.svelte', '**/*.svelte.ts', '**/*.svelte.js'],
+		languageOptions: {
+			parserOptions: {
+				projectService: true,
+				extraFileExtensions: ['.svelte'],
+				parser: ts.parser,
+				svelteConfig
+			}
+		}
+	}
+);