addonova 1.0.2 → 1.0.4

package/README.md

@@ -1,10 +1,10 @@
-# addonova
+# Addonova
 
-Next-Generation Web Extension Framework
+[![Addonova Social Banner](https://raw.githubusercontent.com/code-hemu/addonova/refs/heads/main/docs/assets/capture.jpg)](https://github.com/code-hemu/addonova)
 
-Scaffold and build cross-browser WebExtensions with a modern toolchain.
+Addonova is a framework that allows developers to build extensions for multiple browsers. Developers can easily build, test, and manage extensions.
 
-## Usage
+## Quick Start
 
 ```bash
 npx addonova init my-extension
@@ -21,75 +21,144 @@ npm run release
 - Naver Whale
 - Thunderbird
 
-## Commands
+## CLI Commands
 
 | Command | Description |
-|---------|-------------|
-| `init <name>` | Scaffold a new extension project |
-| `update` | Update workspace/build files to latest template |
-| `build [options]` | Build the extension |
-| `zip` | Create zip bundles |
-| `--help` | Show help |
+| --- | --- |
+| `addonova init <name>` | Scaffold a new extension project |
+| `addonova build [options]` | Build the current extension project |
+| `addonova zip` | Create release zip bundles |
+| `addonova tool` | Open the i18n tools UI in a browser |
+| `addonova --help` | Show help |
 
-## Build Targets
+## Build Scripts
+
+Generated projects include these npm scripts:
+
+```bash
+npm run release
+npm run release:chrome
+npm run release:edge
+npm run release:opera
+npm run release:firefox
+npm run release:thunderbird
+npm run release:naver
+
+npm run debug
+npm run debug:chrome
+npm run debug:edge
+npm run debug:opera
+npm run debug:firefox
+npm run debug:thunderbird
+npm run debug:naver
+
+npm run dev
+npm run zip
+npm test
+```
+
+You can also call the CLI directly:
 
 ```bash
-npm run release                         # Release build (all)
-npm run release:chrome                  # Release (Chrome)
-npm run release:firefox                 # Release (Firefox)
-npm run debug                           # Debug build (all)
-npm run debug:chrome                    # Debug (Chrome)
-npm run watch                           # Watch mode
-npm run zip                             # Create zip bundles
-npx addonova build --all --release      # Build via CLI
-npx addonova --help                     # Show help
+npx addonova build --all --release
+npx addonova build --chrome --debug
+npx addonova build --all --debug --watch
+npx addonova zip
+npx addonova tool
 ```
 
-## Project Structure
+## Build Options
+
+| Option | Description |
+| --- | --- |
+| `--all` | Build all configured browsers |
+| `--chrome` | Build Chrome target |
+| `--edge` | Build Microsoft Edge target |
+| `--firefox` | Build Firefox target |
+| `--opera` | Build Opera target |
+| `--naver` | Build Naver Whale target |
+| `--thunderbird` | Build Thunderbird target |
+| `--release` | Create release build |
+| `--debug` | Create debug build |
+| `--watch` | Rebuild when files change and reload opened extensions |
+| `--open` | Open a browser with the debug extension loaded |
+| `--test` | Build test version |
+| `--version=x.x.x` | Append version to output zip names |
+
+## Dev Mode
 
+```bash
+npm run dev
 ```
+
+Dev mode runs:
+
+```bash
+addonova build --all --debug --watch
+```
+
+Addonova opens an isolated browser profile, loads the unpacked debug extension from `.output/debug/<browser>`, watches source files, rebuilds changed assets, and reloads the extension when the built files change.
+
+## Generated Extension Structure
+
+```txt
 my-extension/
-├── config/                  # Build config per browser
-│   ├── chrome.js
-│   ├── firefox.js
-│   └── ...
-├── platform/                # Platform-specific polyfills
-│   ├── chrome/platform.js
-│   ├── firefox/platform.js
-│   └── ...
-├── src/
-│   ├── _locales/            # i18n locale files (.i18n)
-│   ├── assets/              # Static assets (icons, etc.)
-│   ├── css/                 # Stylesheets
-│   ├── html/                # HTML pages
-│   ├── js/                  # JavaScript source
-│   │   ├── background.js
-│   │   ├── popup.js
-│   │   └── lib/             # Shared runtime libs
-│   └── manifest/            # Manifest JSON templates
-├── .output/                 # Build output
-│   ├── release/             # Release builds
-│   └── debug/               # Debug builds
-└── package.json
+|-- config/
+|-- platform/
+|-- src/
+|   |-- _locales/
+|   |-- assets/
+|   |-- css/
+|   |-- html/
+|   |-- js/
+|   `-- manifest/
+|-- .output/
+`-- package.json
 ```
 
 ## Locales / i18n
 
 Locale files use the `.i18n` format:
 
-```
+```txt
 @extensionName
 My Extension
+
 @extensionDescription
 This is my extension description.
 ```
 
-Run the interactive message manager:
+Run the interactive message manager from a generated project:
+
+```bash
+npm run tool
+```
+
+Or use the i18n tools UI:
+
+```bash
+npx addonova tool
+```
+
+This opens a full UI at `http://localhost:9876` with:
+- **Translate tab** — view all locale messages, add new messages with auto-translation, delete messages
+- **JSON → i18n tab** — drag-and-drop a `messages.json` file to convert to `.i18n` format
+
+## Development
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Check what will be published:
 
 ```bash
-node node_modules/addonova/workspace/tools/translate.js
+npm pack --dry-run
 ```
 
 ## Requirements
 
-- Node.js >= 18
+- Addonova package: Node.js >= 20.19
+- Generated extension template: Node.js >= 22 and npm >= 11

package/bin/addonova.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli/index.js';
+
+await runCli(process.argv.slice(2));

package/bin/index.js

@@ -1,61 +1,2 @@
 #!/usr/bin/env node
-import { fork } from 'node:child_process';
-import process from 'node:process';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { existsSync } from 'node:fs';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-import { init } from '../src/commands/init.js';
-import { update } from '../src/commands/update.js';
-
-const [command, ...args] = process.argv.slice(2);
-
-switch (command) {
-  case 'init':
-    await init(args);
-    break;
-  case 'update':
-    await update();
-    break;
-  case 'build':
-  case 'zip': {
-    const cliPath = resolve(__dirname, '../workspace/tasks/cli.js');
-    if (!existsSync(cliPath)) {
-      console.error('[*] Addonova workspace not found. Reinstall the package.');
-      process.exit(1);
-    }
-    const child = fork(cliPath, [command, ...args], {
-      execArgv: ['--max-old-space-size=3072']
-    });
-    process.on('SIGINT', () => {
-      child.kill('SIGKILL');
-      process.exit(130);
-    });
-    await new Promise((resolve, reject) =>
-      child.on('error', reject).on('close', (code) => {
-        if (code !== 0) process.exit(code);
-        resolve();
-      })
-    );
-    break;
-  }
-  case '--help':
-  case '-h':
-  default:
-    console.log(`
-  Addonova — browser extension toolkit
-
-  Usage:
-    npx addonova init <my-extension>   Scaffold a new extension project
-    npx addonova update                Update workspace/build files in existing project
-    npx addonova build [options]       Build the extension
-    npx addonova zip                   Create zip bundles
-    npx addonova --help                Show this help
-
-  Build options:
-    --all, --chrome, --firefox, --edge, --opera, --naver, --thunderbird
-    --release, --debug, --watch, --test, --version=x.x.x
-    `);
-    break;
-}
+import './addonova.js';

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "addonova",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Web Extension Framework",
   "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
   "bin": {
-    "addonova": "./bin/index.js"
+    "addonova": "./bin/addonova.js"
   },
   "exports": {
     ".": "./src/index.js",
@@ -13,40 +16,28 @@
   "files": [
     "bin/",
     "src/",
-    "workspace/",
-    "template/"
+    "templates/"
   ],
-  "scripts": {
-    "addonova-release": "node --max-old-space-size=3072 workspace/tasks/cli.js build --all --release",
-    "addonova-release:chrome": "node --max-old-space-size=3072 workspace/tasks/cli.js build --chrome --release",
-    "addonova-release:edge": "node --max-old-space-size=3072 workspace/tasks/cli.js build --edge --release",
-    "addonova-release:opera": "node --max-old-space-size=3072 workspace/tasks/cli.js build --opera --release",
-    "addonova-release:firefox": "node --max-old-space-size=3072 workspace/tasks/cli.js build --firefox --release",
-    "addonova-release:thunderbird": "node --max-old-space-size=3072 workspace/tasks/cli.js build --thunderbird --release",
-    "addonova-release:naver": "node --max-old-space-size=3072 workspace/tasks/cli.js build --naver --release",
-    "addonova-debug": "node --max-old-space-size=3072 workspace/tasks/cli.js build --all --debug",
-    "addonova-debug:chrome": "node --max-old-space-size=3072 workspace/tasks/cli.js build --chrome --debug",
-    "addonova-debug:edge": "node --max-old-space-size=3072 workspace/tasks/cli.js build --edge --debug",
-    "addonova-debug:opera": "node --max-old-space-size=3072 workspace/tasks/cli.js build --opera --debug",
-    "addonova-debug:firefox": "node --max-old-space-size=3072 workspace/tasks/cli.js build --firefox --debug",
-    "addonova-debug:thunderbird": "node --max-old-space-size=3072 workspace/tasks/cli.js build --thunderbird --debug",
-    "addonova-debug:naver": "node --max-old-space-size=3072 workspace/tasks/cli.js build --naver --debug",
-    "addonova-watch": "node --max-old-space-size=3072 workspace/tasks/cli.js build --all --debug --watch"
-  },
   "dependencies": {
-    "@craftamap/esbuild-plugin-html": "^0.9.0",
     "chokidar": "^5.0.0",
     "esbuild": "^0.27.3",
     "globby": "^16.1.0",
+    "html-minifier-terser": "^7.2.0",
+    "htmlhint": "^1.9.2",
+    "web-ext": "^10.3.0",
     "yazl": "^3.3.1"
   },
+  "overrides": {
+    "encoding-sniffer": "^1.0.2",
+    "jsdom": "^29.1.1"
+  },
   "keywords": [
-    "webextension",
-    "browser-extension",
-    "chrome-extension",
-    "firefox-addon",
-    "scaffold",
-    "cli"
+    "chrome",
+    "web",
+    "extension",
+    "browser",
+    "bundler",
+    "framework"
   ],
   "license": "ISC",
   "author": "Hemanta gayen",
@@ -59,6 +50,6 @@
     "url": "https://github.com/code-hemu/addonova/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19"
   }
 }

package/src/build/browser.js

@@ -0,0 +1,143 @@
+import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { createRequire } from 'node:module';
+
+import { getDestDir } from './paths.js';
+import { log } from './utils.js';
+
+const WEB_EXT_TARGETS = new Set(['chrome', 'edge', 'firefox', 'opera', 'naver']);
+const require = createRequire(import.meta.url);
+
+const chromiumBinaries = {
+  edge: {
+    win32: [
+      'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+      'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+    ],
+    darwin: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+    linux: ['microsoft-edge', 'microsoft-edge-stable'],
+  },
+  opera: {
+    win32: [
+      'C:\\Users\\%USERNAME%\\AppData\\Local\\Programs\\Opera\\opera.exe',
+      'C:\\Program Files\\Opera\\opera.exe',
+    ],
+    darwin: ['/Applications/Opera.app/Contents/MacOS/Opera'],
+    linux: ['opera'],
+  },
+  naver: {
+    win32: [
+      'C:\\Program Files\\Naver\\Naver Whale\\Application\\whale.exe',
+      'C:\\Program Files (x86)\\Naver\\Naver Whale\\Application\\whale.exe',
+    ],
+    darwin: ['/Applications/Whale.app/Contents/MacOS/Whale'],
+    linux: ['whale'],
+  },
+};
+
+function expandEnv(value) {
+  return value.replace(/%([^%]+)%/g, (_, name) => process.env[name] ?? '');
+}
+
+function resolveBinary(platform) {
+  const candidates = chromiumBinaries[platform]?.[process.platform] ?? [];
+
+  for (const candidate of candidates) {
+    const binary = expandEnv(candidate);
+    if (process.platform === 'linux' || existsSync(binary)) {
+      return binary;
+    }
+  }
+
+  return null;
+}
+
+function getWebExtBin() {
+  try {
+    const webExtIndex = require.resolve('web-ext');
+    return join(dirname(webExtIndex), 'bin', 'web-ext.js');
+  } catch {
+    return null;
+  }
+}
+
+function createWebExtArgs(platform, settings) {
+  const sourceDir = resolve(getDestDir({ isDebug: settings.isDebug, platform }));
+  const profileDir = resolve(join('.output', 'profiles', platform));
+  const args = [
+    'run',
+    '--source-dir',
+    sourceDir,
+    '--no-input',
+    '--start-url',
+    'about:blank',
+  ];
+
+  if (platform === 'firefox') {
+    args.push('--target', 'firefox-desktop', '--firefox-profile', profileDir);
+    return { args, sourceDir, profileDir };
+  }
+
+  args.push('--target', 'chromium', '--chromium-profile', profileDir, '--profile-create-if-missing');
+
+  if (platform !== 'chrome') {
+    const binary = resolveBinary(platform);
+    if (binary) {
+      args.push('--chromium-binary', binary);
+    } else {
+      log.warn(`[!] ${platform} binary not found. Trying the default Chromium browser.`);
+    }
+  }
+
+  return { args, sourceDir, profileDir };
+}
+
+export async function startBrowserRunners(settings) {
+  const webExtBin = getWebExtBin();
+  const platforms = settings.platforms.filter((platform) => WEB_EXT_TARGETS.has(platform));
+
+  if (!webExtBin || !existsSync(webExtBin)) {
+    log.warn('[!] Browser dev runner not found. Run npm install before dev mode.');
+    return;
+  }
+
+  if (platforms.length === 0) {
+    log.warn('[!] Browser dev mode supports Chrome, Edge, Firefox, Opera, and Naver Whale.');
+    return;
+  }
+
+  settings.browserRunners = [];
+
+  for (const platform of platforms) {
+    const { args, sourceDir, profileDir } = createWebExtArgs(platform, settings);
+
+    if (!existsSync(sourceDir)) {
+      log.warn(`[!] Extension output missing for ${platform}: ${sourceDir}`);
+      continue;
+    }
+
+    await mkdir(profileDir, { recursive: true });
+
+    const child = spawn(process.execPath, [webExtBin, ...args], {
+      stdio: 'inherit',
+    });
+
+    child.on('exit', (code) => {
+      if (code !== null && code !== 0) {
+        log.warn(`[!] Browser runner for ${platform} exited with code ${code}`);
+      }
+    });
+
+    settings.browserRunners.push(child);
+    log.ok(`[+] Started browser runner for ${platform}`);
+  }
+}
+
+export function stopBrowserRunners(settings) {
+  for (const child of settings.browserRunners ?? []) {
+    if (!child.killed) child.kill('SIGTERM');
+  }
+}

package/{workspace/tasks → src/build}/build.js

@@ -8,6 +8,7 @@ import bundleLocales from './bundle-locales.js';
 import bundleManifest from './bundle-manifest.js';
 import assetsCopy from './copy.js';
 import zip from './zip.js';
+import { startBrowserRunners, stopBrowserRunners } from './browser.js';
 import {log} from './utils.js';
 import {runTasks} from './task.js';
 
@@ -53,7 +54,9 @@ const settings = {
     isDebug: args.includes('--debug'),
     isTest: args.includes('--test'),
     logInfo: args.includes('--log-info'),
-    logWarn: args.includes('--log-warn')
+    logWarn: args.includes('--log-warn'),
+    shouldRunBrowser: args.includes('--open') || (args.includes('--watch') && args.includes('--debug')),
+    args,
 }
 
 const standardTask = [
@@ -77,7 +80,18 @@ const buildTask = [
     try {
         await runTasks(settings.isDebug ? standardTask : buildTask, settings);
         if (settings.isWatch) {
-            standardTask.forEach((task) => task.watch(settings.platforms, settings.isDebug));
+            if (settings.shouldRunBrowser) {
+                await startBrowserRunners(settings);
+                process.on('exit', () => stopBrowserRunners(settings));
+                process.on('SIGINT', () => {
+                    stopBrowserRunners(settings);
+                    process.exit(130);
+                });
+            }
+            standardTask.forEach((task) => task.watch(
+                settings.platforms,
+                settings.isDebug
+            ));
             log.ok('[^_^] Watching...');
         } else {
             log.ok('MISSION PASSED! RESPECT +');

package/src/build/bundle-html.js

@@ -0,0 +1,120 @@
+import path from 'node:path';
+import { minify } from 'html-minifier-terser';
+import htmlhint from 'htmlhint';
+
+import { getDestDir } from './paths.js';
+import { readFile, writeFile, getConfig, getAllFiles, log, fileExistsInConfig } from './utils.js';
+import { createTask } from './task.js';
+
+const srcHTMLDir = 'src/html';
+const { HTMLHint } = htmlhint;
+
+const htmlHintRules = {
+  'attr-lowercase': true,
+  'attr-no-duplication': true,
+  'doctype-first': false,
+  'id-unique': true,
+  'tag-pair': true,
+  'tagname-lowercase': true,
+};
+
+const htmlMinifyOptions = {
+  collapseBooleanAttributes: true,
+  collapseWhitespace: true,
+  conservativeCollapse: true,
+  keepClosingSlash: true,
+  minifyCSS: true,
+  minifyJS: true,
+  removeComments: true,
+  removeEmptyAttributes: false,
+};
+
+function getDestinationFile(destDir, dest, src, filename) {
+  const sourceName = path.basename(src, path.extname(src));
+  const outputName = `${filename.replace('[name]', sourceName)}.html`;
+  return path.join(destDir, dest, outputName);
+}
+
+function formatHtmlIssue(file, issue) {
+  return `${file}:${issue.line}:${issue.col} ${issue.type.toUpperCase()} ${issue.message}`;
+}
+
+function validateHTML(file, html) {
+  const issues = HTMLHint.verify(html, htmlHintRules);
+  const errors = issues.filter((issue) => issue.type === 'error');
+
+  if (errors.length > 0) {
+    throw new Error(errors.map((issue) => formatHtmlIssue(file, issue)).join('\n'));
+  }
+
+  for (const issue of issues) {
+    log.warn(`[HTML] ${formatHtmlIssue(file, issue)}`);
+  }
+}
+
+async function bundleHTML(config, isDebug, platform) {
+  const dir = getDestDir({ isDebug, platform });
+
+  for (const [dest, sources] of Object.entries(config.entry)) {
+    for (const src of sources) {
+      const html = await readFile(src, 'utf8');
+      validateHTML(src, html);
+
+      const output = isDebug
+        ? html
+        : await minify(html, htmlMinifyOptions);
+
+      await writeFile(
+        getDestinationFile(dir, dest, src, config.filename),
+        output,
+        'utf8'
+      );
+    }
+  }
+}
+
+export function createBundleHTMLTask(srcHTMLDir) {
+  const runBundleHTML = async ({ platforms, isDebug, logInfo, logWarn }) => {
+    for (const platform of platforms) {
+      const config = await getConfig(platform);
+      if (config.html) {
+        await bundleHTML(config.html, isDebug, platform);
+        if (logInfo) log.ok(`Bundling HTML for ${platform}...`);
+      } else if (logWarn) {
+        log.warn(`No HTML config found for ${platform}, skipping HTML bundling.`);
+      }
+    }
+  };
+
+  const onChange = async (changedFiles, watcher, platforms, isDebug) => {
+    for (const platform of platforms) {
+      const config = await getConfig(platform);
+
+      if (!config.html) continue;
+      const exists = await fileExistsInConfig(
+        config.html.entry,
+        changedFiles[0]
+      );
+
+      if (exists) {
+        const newConfig = {
+          html: {
+            entry: exists,
+            filename: config.html.filename,
+          },
+        };
+        await bundleHTML(newConfig.html, isDebug, platform);
+      }
+    }
+  };
+
+  return createTask(
+    'bundle HTML',
+    runBundleHTML
+  ).addWatcher(
+    () => getAllFiles(srcHTMLDir),
+    onChange
+  );
+}
+
+export default createBundleHTMLTask(srcHTMLDir);

package/{workspace/tasks → src/build}/cli.js

@@ -21,10 +21,11 @@ function printHelp() {
         'Other parameters:',
         '  --release       Build release version (default)',
         '  --debug         Build debug version',
-        '  --watch         Watch for changes and rebuild automatically',
+        '  --watch         Watch for changes and reload opened extensions',
         '  --log-info      Log info messages',
         '  --log-warn      Log warning messages',
         '  --test          Build test version (for testing in development environment)',
+        '  --open          Open a browser with the debug extension loaded',
         '  --version=1.2.3 Append version to output file name (e.g. extension-name-chrome-1.2.3.zip)',
         '  -h, --help      Show this help message',
     ].join('\n'));
@@ -57,6 +58,7 @@ function validateArguments(args) {
         '--log-info',
         '--log-warn',
         '--test',
+        '--open',
         '--version=*',
         '--help',
         '-h'
@@ -82,7 +84,7 @@ async function run() {
     const validationErrors = validateArguments(args);
     if (validationErrors.length > 0) {
         validationErrors.forEach(log.error);
-        log.error('❌ No target platform specified.');
+        log.error('[X] No target platform specified.');
         printHelp();
         process.exit(130);
     }