@mahe_pkm/buzl-html-editor 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) 2026 Buzl. All rights reserved.
+
+This package is proprietary software. Publication to a package registry does
+not grant permission to copy, modify, redistribute, sublicense, or sell the
+software. Use is limited to people and organizations authorized by Buzl.

package/README.md

@@ -0,0 +1,113 @@
+# Buzl HTML Editor
+
+A local visual editor and static-site server for ordinary multi-page HTML, CSS,
+and JavaScript websites. It includes Live Edit, image uploads, AVIF image
+optimization, AI-assisted text, and AI image generation.
+
+The server is local-only by default. It edits the website folder from which it
+is started; the editor's own files stay inside the npm package.
+
+## Requirements
+
+- Node.js 18 or newer
+- Node.js 20 LTS or newer is recommended
+- A static website containing one or more `.html` files
+
+## Install
+
+Run this inside the website root:
+
+```bash
+npm install --save-dev @mahe_pkm/buzl-html-editor
+```
+
+## Start the website and editor
+
+```bash
+npx buzl-editor
+```
+
+Default addresses:
+
+- Website: `http://localhost:4000/`
+- Editor: `http://localhost:4000/admin/`
+
+Use another port or website folder when needed:
+
+```bash
+npx buzl-editor --port 4500
+npx buzl-editor --root "C:\Websites\client-site" --port 4500
+```
+
+Prevent automatic browser opening:
+
+```bash
+npx buzl-editor --no-open
+```
+
+## Website-only mode
+
+```bash
+npx buzl-site
+npx buzl-site --port 3500
+```
+
+Website-only mode blocks the editor, APIs, dependencies, configuration,
+development files, and local secrets.
+
+## Setup and diagnostics
+
+Initialize optional configuration in the current website:
+
+```bash
+npx buzl-editor init
+```
+
+This creates `.buzl/config.json`, `.env.example`, and safe `.gitignore` rules
+without replacing existing files.
+
+Inspect a website before editing:
+
+```bash
+npx buzl-editor doctor
+```
+
+## Optional configuration
+
+`.buzl/config.json`:
+
+```json
+{
+  "editorPort": 4000,
+  "websitePort": 3000,
+  "host": "127.0.0.1",
+  "open": true
+}
+```
+
+Command-line options take priority over environment variables, configuration,
+and defaults.
+
+## AI configuration
+
+Create `.env` in the client website root. Never commit this file.
+
+```dotenv
+ANTHROPIC_API_KEY=
+OPENROUTER_API_KEY=
+```
+
+The editor and image uploads work without the AI keys. Only the related AI
+actions require them.
+
+## Safety
+
+- The default bind address is `127.0.0.1`.
+- Non-local binding requires both `--host` and `--allow-network`.
+- The editor can only load and save HTML files inside the selected website.
+- Each save creates a recoverable copy under `.buzl/backups/`.
+- Uploaded raster images are optimized to AVIF under `assets/images/`.
+- `.env`, `.git`, `.buzl`, `node_modules`, tests, package metadata, and server
+  source are not publicly served.
+
+Press `Ctrl+C` to stop either server.

package/bin/buzl-editor.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const path = require('path');
+const {
+  askForPort,
+  checkPort,
+  ensureSiteRoot,
+  initializeSite,
+  openBrowser,
+  parseArgs,
+  resolveRuntimeOptions,
+  runDoctor,
+} = require('../lib/cli');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const DEFAULTS = { configPortKey: 'editorPort', host: '127.0.0.1', open: true, port: 4000 };
+
+function printHelp() {
+  console.log(`
+Buzl HTML Editor
+
+Usage:
+  buzl-editor [--root <folder>] [--port <number>] [--no-open]
+  buzl-editor init [--root <folder>]
+  buzl-editor doctor [--root <folder>] [--port <number>]
+
+Options:
+  --root <folder>    Website root (default: current folder)
+  --port, -p         Local port (default: 4000)
+  --host <address>   Bind address (default: 127.0.0.1)
+  --allow-network    Required for a non-local bind address
+  --open             Open the editor in the default browser
+  --no-open          Do not open a browser
+  --version, -v      Show package version
+  --help, -h         Show this help
+`);
+}
+
+async function main() {
+  try {
+    if (Number(process.versions.node.split('.')[0]) < 18) {
+      throw new Error('Node.js 18 or newer is required. Node.js 20 LTS is recommended.');
+    }
+
+    const parsed = parseArgs(process.argv.slice(2), DEFAULTS);
+    if (parsed.command === 'help') return printHelp();
+    if (parsed.command === 'version') {
+      console.log(require('../package.json').version);
+      return;
+    }
+
+    ensureSiteRoot(parsed.root);
+    let options = resolveRuntimeOptions(parsed, DEFAULTS);
+    if (!options.portConfigured) {
+      options.port = await askForPort('editor', DEFAULTS.port);
+    }
+
+    const envPath = path.join(options.root, '.env');
+    process.env.BUZL_SITE_ROOT = options.root;
+    process.env.BUZL_ENV_FILE = envPath;
+    process.env.BUZL_CONTEXT_FILE = path.join(options.root, 'website_context.json');
+    process.env.HOST = options.host;
+    process.env.PORT = String(options.port);
+    require('dotenv').config({ path: envPath });
+
+    if (parsed.command === 'init') {
+      initializeSite(options.root);
+      return;
+    }
+    if (parsed.command === 'doctor') {
+      runDoctor(options.root, options.port, options.host);
+      await checkPort(options.port, options.host)
+        .then(() => console.log(`Port ${options.port}: available`))
+        .catch((error) => console.warn(`Port ${options.port}: ${error.message}`));
+      return;
+    }
+
+    await checkPort(options.port, options.host);
+    const app = require(path.join(PACKAGE_ROOT, 'dist', 'server.js'));
+    const server = app.listen(options.port, options.host, () => {
+      const siteUrl = `http://localhost:${options.port}/`;
+      const editorUrl = `http://localhost:${options.port}/admin/`;
+      console.log('\nBuzl website and editor are running.');
+      console.log(`Website: ${siteUrl}`);
+      console.log(`Editor:  ${editorUrl}`);
+      console.log(`Root:    ${options.root}`);
+      console.log('Press Ctrl+C to stop.\n');
+      if (options.open) openBrowser(editorUrl);
+    });
+
+    const stop = () => server.close(() => process.exit(0));
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+  } catch (error) {
+    console.error(`\nUnable to start Buzl Editor: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/bin/buzl-site.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const path = require('path');
+const {
+  askForPort,
+  checkPort,
+  ensureSiteRoot,
+  openBrowser,
+  parseArgs,
+  resolveRuntimeOptions,
+  runDoctor,
+} = require('../lib/cli');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const DEFAULTS = { configPortKey: 'websitePort', host: '127.0.0.1', open: true, port: 3000 };
+
+function printHelp() {
+  console.log(`
+Buzl static website server
+
+Usage:
+  buzl-site [--root <folder>] [--port <number>] [--no-open]
+  buzl-site doctor [--root <folder>] [--port <number>]
+
+The editor, APIs, package files and private configuration are unavailable in
+website-only mode.
+`);
+}
+
+async function main() {
+  try {
+    const parsed = parseArgs(process.argv.slice(2), DEFAULTS);
+    if (parsed.command === 'help') return printHelp();
+    if (parsed.command === 'version') {
+      console.log(require('../package.json').version);
+      return;
+    }
+    if (parsed.command === 'init') {
+      throw new Error('Use "buzl-editor init" to initialize a website.');
+    }
+
+    ensureSiteRoot(parsed.root);
+    let options = resolveRuntimeOptions(parsed, DEFAULTS);
+    if (!options.portConfigured) {
+      options.port = await askForPort('website', DEFAULTS.port);
+    }
+    if (parsed.command === 'doctor') {
+      runDoctor(options.root, options.port, options.host);
+      return;
+    }
+
+    await checkPort(options.port, options.host);
+    process.env.BUZL_SITE_ROOT = options.root;
+    const { createSiteServer } = require(path.join(PACKAGE_ROOT, 'dist', 'site-server.js'));
+    const server = createSiteServer({ siteRoot: options.root });
+    server.listen(options.port, options.host, () => {
+      const siteUrl = `http://localhost:${options.port}/`;
+      console.log('\nBuzl public website is running.');
+      console.log(`Website: ${siteUrl}`);
+      console.log(`Root:    ${options.root}`);
+      console.log('The editor and APIs are disabled in this mode.');
+      console.log('Press Ctrl+C to stop.\n');
+      if (options.open) openBrowser(siteUrl);
+    });
+
+    const stop = () => server.close(() => process.exit(0));
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+  } catch (error) {
+    console.error(`\nUnable to start Buzl website: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}
+
+main();

package/dist/imageOptimizer.js

@@ -0,0 +1,68 @@
+const sharp = require('sharp');
+const fs = require('fs');
+
+const MAX_DIMENSION = 2048;
+const MAX_SIZE_BYTES = 1 * 1024 * 1024; // 1 MB cap
+const AVIF_QUALITY_LADDER = [70, 60, 50, 40, 30];
+
+/**
+ * Compresses an image (buffer or file path) strictly to AVIF.
+ * Loops through quality ladder to fit within MAX_SIZE_BYTES.
+ * If it doesn't fit, writes the lowest quality (30) AVIF.
+ * 
+ * @param {Buffer|string} inputBufferOrPath - Input image buffer or absolute file path
+ * @param {string} outPathWithoutExt - Target output path without the .avif extension
+ * @returns {Promise<{format: 'avif', path: string, size: number}>}
+ */
+async function compressImage(inputBufferOrPath, outPathWithoutExt) {
+  // Read metadata
+  const pipeline = sharp(inputBufferOrPath, { failOn: 'none' });
+  const meta = await pipeline.metadata();
+  
+  const originalWidth = meta.width;
+  const originalHeight = meta.height;
+  if (!originalWidth || !originalHeight) {
+    throw new Error('Could not read image dimensions');
+  }
+
+  const needsResize = Math.max(originalWidth, originalHeight) > MAX_DIMENSION;
+  const buildPipeline = () => {
+    let p = sharp(inputBufferOrPath, { failOn: 'none' });
+    if (needsResize) {
+      p = p.resize({
+        width: MAX_DIMENSION,
+        height: MAX_DIMENSION,
+        fit: 'inside',
+        withoutEnlargement: true
+      });
+    }
+    return p;
+  };
+
+  const finalPath = outPathWithoutExt + '.avif';
+  let smallestBuffer = null;
+
+  // Try AVIF quality levels
+  for (const quality of AVIF_QUALITY_LADDER) {
+    const { data } = await buildPipeline()
+      .avif({ quality, effort: 4 })
+      .toBuffer({ resolveWithObject: true });
+    
+    if (!smallestBuffer || data.length < smallestBuffer.length) {
+      smallestBuffer = data;
+    }
+
+    if (data.length <= MAX_SIZE_BYTES) {
+      await fs.promises.writeFile(finalPath, data);
+      return { format: 'avif', path: finalPath, size: data.length };
+    }
+  }
+
+  // If nothing fit within 1MB budget, write the smallest AVIF buffer (quality 30)
+  await fs.promises.writeFile(finalPath, smallestBuffer);
+  return { format: 'avif', path: finalPath, size: smallestBuffer.length };
+}
+
+module.exports = {
+  compressImage
+};

package/dist/imageService.js

@@ -0,0 +1,242 @@
+/**
+ * imageService.js
+ *
+ * Image generation service using OpenRouter APIs.
+ * JS port of tools/imageService.ts — simplified for the admin backend.
+ *
+ * Supports:
+ *   - Image generation with model fallback
+ *   - Request cancellation via AbortController
+ *   - Saving generated images to disk
+ *
+ * Environment variables (.env):
+ *   OPENROUTER_API_KEY
+ *   OPENROUTER_BASE_URL            (default: https://openrouter.ai/api/v1)
+ *   OPENROUTER_IMAGE_MODEL         (default: google/gemini-3.1-flash-image-preview)
+ *   OPENROUTER_IMAGE_FALLBACK_MODELS (comma-separated)
+ */
+
+// ─── OpenRouterClient ───────────────────────────────────────────────────────
+
+class OpenRouterClient {
+  constructor({ apiKey, baseUrl }) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+  }
+
+  /**
+   * Generate an image from a text prompt.
+   * Returns base64 image data.
+   * @param {string} prompt
+   * @param {string} model
+   * @param {AbortSignal} [signal] - optional AbortSignal for cancellation
+   */
+  async generateImage(prompt, model, signal) {
+    console.log(`  🖼️  ImageGen → model: ${model}`);
+
+    const data = await this._post('/chat/completions', {
+      model,
+      stream: false,
+      messages: [{ role: 'user', content: prompt }],
+    }, signal);
+
+    const choices = data?.choices;
+    if (!choices || choices.length === 0) {
+      throw new Error('No choices returned from image generation API');
+    }
+
+    const message = choices[0].message;
+    return this._extractBase64(message?.content, message?.images);
+  }
+
+  /**
+   * POST to OpenRouter using native fetch (Node 18+).
+   * Handles large responses (image base64 payloads can be 200KB+) reliably.
+   */
+  async _post(path, body, signal) {
+    // Ensure baseUrl ends with '/' so relative path appends correctly
+    const base = this.baseUrl.endsWith('/') ? this.baseUrl : this.baseUrl + '/';
+    const url = new URL(path.replace(/^\//, ''), base).toString();
+
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+
+    const raw = await res.text();
+    let json;
+    try {
+      json = JSON.parse(raw);
+    } catch (e) {
+      // OpenRouter may return SSE streaming format even when stream:false is set.
+      // Detect and parse SSE "data: {...}" lines, merging them into one response.
+      if (raw.trimStart().startsWith('data:')) {
+        console.log(`  ℹ️  Received SSE stream response, parsing chunks…`);
+        json = this._parseSSE(raw);
+      }
+      if (!json) {
+        console.error(`  ❌  OpenRouter parse error: status=${res.status}, body length=${raw.length}, first 300 chars: ${raw.substring(0, 300)}`);
+        throw new Error(`Failed to parse OpenRouter response (status ${res.status}, ${raw.length} bytes)`);
+      }
+    }
+
+    if (!res.ok) {
+      const err = new Error(json?.error?.message || `HTTP ${res.status}`);
+      err.status = res.status;
+      throw err;
+    }
+
+    return json;
+  }
+
+  /**
+   * Parse SSE (Server-Sent Events) stream into a merged chat completion object.
+   * OpenRouter may return SSE format unexpectedly for image generation requests.
+   */
+  _parseSSE(raw) {
+    const lines = raw.split('\n');
+    let merged = null;
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('data:')) continue;
+      const payload = trimmed.slice(5).trim();
+      if (payload === '[DONE]') break;
+
+      try {
+        const chunk = JSON.parse(payload);
+        if (!merged) {
+          // Use the first chunk as the base structure
+          merged = chunk;
+          // SSE chunks use "delta" instead of "message" in choices
+          if (merged.choices?.[0]?.delta && !merged.choices[0].message) {
+            merged.choices[0].message = { ...merged.choices[0].delta };
+          }
+        } else {
+          // Merge subsequent delta content into the message
+          const delta = chunk.choices?.[0]?.delta;
+          if (delta && merged.choices?.[0]?.message) {
+            const msg = merged.choices[0].message;
+            if (delta.content) {
+              msg.content = (msg.content || '') + delta.content;
+            }
+            if (delta.images) {
+              msg.images = (msg.images || []).concat(delta.images);
+            }
+          }
+        }
+      } catch (parseErr) {
+        // Skip malformed chunks
+        continue;
+      }
+    }
+
+    return merged;
+  }
+
+  /**
+   * Extract base64 data from API response.
+   * Checks both `images` array and `content` field.
+   */
+  _extractBase64(content, images) {
+    // Check `images` array (OpenRouter Gemini models return data here)
+    if (Array.isArray(images)) {
+      for (const item of images) {
+        if (item.type === 'image_url' && item.image_url?.url) {
+          const url = item.image_url.url;
+          const match = url.match(/^data:image\/[^;]+;base64,(.+)$/s);
+          if (match) return match[1];
+          return url;
+        }
+      }
+    }
+
+    // Content is array with image_url objects
+    if (Array.isArray(content)) {
+      for (const item of content) {
+        if (item.type === 'image_url' && item.image_url?.url) {
+          const url = item.image_url.url;
+          const match = url.match(/^data:image\/[^;]+;base64,(.+)$/s);
+          if (match) return match[1];
+          return url;
+        }
+      }
+    }
+
+    // Content is a string data URI
+    if (typeof content === 'string') {
+      const match = content.match(/^data:image\/[^;]+;base64,(.+)$/s);
+      if (match) return match[1];
+    }
+
+    throw new Error('Unable to extract image data from API response');
+  }
+}
+
+// ─── ImageGenerator ─────────────────────────────────────────────────────────
+
+class ImageGenerator {
+  /**
+   * @param {OpenRouterClient} client
+   * @param {{ primaryModel: string, fallbackModels: string[] }} config
+   */
+  constructor(client, config) {
+    this.client = client;
+    this.primaryModel = config.primaryModel;
+    this.fallbackModels = config.fallbackModels || [];
+  }
+
+  /**
+   * Generate an image. Tries primary model, then fallbacks.
+   * @param {string} prompt
+   * @param {AbortSignal} [signal]
+   * @returns {Promise<{ imageBase64: string, model: string }>}
+   */
+  async generate(prompt, signal) {
+    const models = [this.primaryModel, ...this.fallbackModels];
+
+    for (const model of models) {
+      try {
+        console.log(`  🎨  Trying model: ${model}`);
+        const imageBase64 = await this.client.generateImage(prompt, model, signal);
+        return { imageBase64, model };
+      } catch (err) {
+        // Propagate cancellation immediately
+        if (err.name === 'AbortError' || err.message === 'Request cancelled') {
+          throw new Error('Request cancelled');
+        }
+        console.warn(`  ⚠️  Model ${model} failed: ${err.message}`);
+        // Fall through to try next model
+      }
+    }
+
+    throw new Error(`All models failed: [${models.join(', ')}]`);
+  }
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Create an ImageGenerator from environment variables.
+ */
+function createImageGenerator() {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    throw new Error('OPENROUTER_API_KEY is required. Set it in admin/.env');
+  }
+
+  const baseUrl = process.env.OPENROUTER_BASE_URL || 'https://openrouter.ai/api/v1';
+  const primaryModel = process.env.OPENROUTER_IMAGE_MODEL || 'google/gemini-3.1-flash-image-preview';
+  const fallbackModelsRaw = process.env.OPENROUTER_IMAGE_FALLBACK_MODELS || 'google/gemini-2.5-flash-image';
+  const fallbackModels = fallbackModelsRaw.split(',').map(m => m.trim()).filter(Boolean);
+
+  const client = new OpenRouterClient({ apiKey, baseUrl });
+  return new ImageGenerator(client, { primaryModel, fallbackModels });
+}
+
+module.exports = { OpenRouterClient, ImageGenerator, createImageGenerator };