@omega.js/extension 0.1.0

package/dist/gulp/tasks/serve.js

@@ -0,0 +1,103 @@
+// Libraries
+const Manager = new (require('../../build.js'));
+const logger = Manager.logger('serve');
+const path = require('path');
+const WebSocket = require('ws');
+const { watchEnvChain } = require('../../vendor/devkit/env-watch.js');
+
+// Load package
+const package = Manager.getPackage('main');
+const project = Manager.getPackage('project');
+const config = Manager.getConfig('project');
+const rootPathPackage = Manager.getRootPath('main');
+const rootPathProject = Manager.getRootPath('project');
+
+/**
+ * The ENV lane's watcher (#681): every layer of the `.env` chain — company,
+ * brand, this target — and each layer's `.env.<environment>` overlay. A change
+ * reloads the cascade into process.env, so the next task rebuild (the sass /
+ * bundle / package watchers all re-run in THIS process) reads the new values.
+ * The log line names the FILE, never a value. Resolution and watching live in
+ * @omega.js/devkit/env-watch, shared with the web and desktop dev lanes; this
+ * binds the extension's own target name.
+ *
+ * Scope, exactly: a NEW key AND an EDITED value both land on that next rebuild,
+ * and a key dropped from the file is dropped from the process — `reloadEnv`
+ * re-reads what a file layer owns
+ * ([#724](https://github.com/Omega-JS-Stack/omega/issues/724)). A SHELL-set
+ * value still wins over every file, whatever the file now says.
+ *
+ * `serve` is where it arms because it is the dev lane's only task — the build
+ * series never includes it, so a one-shot build never opens a watch it would
+ * have to close.
+ * @param {string} root - the target root
+ * @param {object} [options]
+ * @param {string} [options.environment] - the environment whose overlay counts
+ * @returns {{ inputs: Array<{ layer: string, path: string }>, close: function }}
+ */
+function watchEnvSources(root, options) {
+  return watchEnvChain({
+    projectDir: root,
+    target: 'extension',
+    environment: options && options.environment,
+    log: (line) => logger.log(line),
+  });
+}
+
+// Task
+module.exports = function serve(complete) {
+  // Log
+  logger.log('Starting...');
+
+  // The .env chain is a dev INPUT too (#681)
+  watchEnvSources(rootPathProject);
+
+  // N7: resolve the livereload port through the allocator — taken → +1, so
+  // two targets of one brand (extension + desktop serve) land on distinct
+  // ports automatically. Config `ports.livereload` pins (busy pin = error).
+  // The resolved value publishes via OMEGA_LIVERELOAD_PORT BEFORE any build
+  // task bakes it (the bundle task's replacements + package.js), so the built
+  // extension always connects to THIS server.
+  const { resolvePorts, envPort, CLASSIC_PORTS } = require('../../vendor/config/index.js');
+  const pins = {};
+  if (typeof config.ports?.livereload === 'number') {
+    pins.livereload = config.ports.livereload;
+  }
+
+  return resolvePorts({ wanted: { livereload: envPort('livereload') || CLASSIC_PORTS.livereload }, pins })
+    .then(({ ports, bumped }) => {
+      process.env.OMEGA_LIVERELOAD_PORT = String(ports.livereload);
+      if (bumped.length) {
+        logger.log(`LiveReload port bumped to ${ports.livereload} (classic taken — another target's serve?)`);
+      }
+
+      try {
+        // Get the local URL
+        const server = new WebSocket.Server({ port: ports.livereload })
+
+        // Log
+        logger.log(`LiveReload server started on port ${ports.livereload}`);
+
+        // Log connection
+        server.on('connection', (socket, request) => {
+          logger.log(`LiveReload client connected from local IP: ${request.socket.localAddress}`);
+        });
+
+        // Handle errors
+        server.on('error', (error) => {
+          logger.error('WebSocket error:', error);
+        });
+
+        // Set server
+        global.websocket = server;
+      } catch (error) {
+        // Log error
+        logger.error('Error starting LiveReload server:', error);
+      }
+
+      // Complete
+      return complete();
+    });
+};
+
+module.exports.watchEnvSources = watchEnvSources;

package/dist/gulp/tasks/translate.js

@@ -0,0 +1,252 @@
+// Libraries
+const Manager = new (require('../../build.js'));
+const logger = Manager.logger('translate');
+const { series } = require('gulp');
+const jetpack = require('fs-jetpack');
+const path = require('path');
+const JSON5 = require('json5');
+const {
+  resolveProvider,
+  resolveTranslationSettings,
+  translateStrings,
+  languageName,
+  hashKey,
+  loadCache,
+  saveCache,
+} = require('../../vendor/devkit/translate/index.js');
+
+// Locale field limits (shared with audit.js)
+const { limits: LOCALE_LIMITS } = require('../config/locales.js');
+
+// Paths
+const configMessagesPath = path.join(process.cwd(), 'config', 'messages.json');
+const configDescriptionPath = path.join(process.cwd(), 'config', 'description.md');
+const distLocalesDir = path.join(process.cwd(), 'dist', '_locales');
+
+// Committed per-string cache (replaces the legacy gitignored .cache/):
+// translations/{lang}/messages.json (hash → translated message) and
+// translations/{lang}/description.md (translated markdown + source marker)
+const translationsDir = path.join(process.cwd(), 'translations');
+
+// First line of a translated description — records the source hash so a
+// source edit invalidates it; stripped when the file is consumed
+const DESCRIPTION_MARKER = /^<!-- omega:source ([0-9a-f]{12}) -->\n?/;
+
+// Helper: Read and parse config/messages.json (JSON5 → object)
+function readConfigMessages() {
+  if (!jetpack.exists(configMessagesPath)) {
+    return null;
+  }
+
+  try {
+    return JSON5.parse(jetpack.read(configMessagesPath));
+  } catch (e) {
+    logger.error(`Failed to parse config/messages.json: ${e.message}`);
+    return null;
+  }
+}
+
+// Helper: translation settings from the RESOLVED config (brand root included)
+function getSettings() {
+  return resolveTranslationSettings(Manager.getConfig());
+}
+
+// Helper: compose a locale's messages.json from the EN source + cache
+// (missing translations fall back to English so the file is always complete)
+function composeMessages(enMessages, lang, baseDir) {
+  const cache = loadCache(baseDir || translationsDir, lang, 'messages');
+  const composed = {};
+
+  for (const [key, entry] of Object.entries(enMessages)) {
+    composed[key] = {
+      ...entry,
+      message: cache[hashKey(entry.message)] ?? entry.message,
+    };
+  }
+
+  return composed;
+}
+
+// Deploy locales to dist/_locales/ — EN from config, translations from the
+// committed cache. Always runs (dev + build) so package has all locale files.
+async function deployTranslations(complete) {
+  const enMessages = readConfigMessages();
+  if (!enMessages) {
+    logger.warn('config/messages.json not found or invalid, skipping');
+    return complete();
+  }
+
+  // EN straight from config
+  jetpack.write(path.join(distLocalesDir, 'en', 'messages.json'), JSON.stringify(enMessages, null, 2));
+
+  // Configured languages from the committed cache (none when disabled)
+  const settings = getSettings();
+  const languages = settings.enabled ? settings.languages : [];
+  let count = 0;
+
+  for (const lang of languages) {
+    jetpack.write(
+      path.join(distLocalesDir, lang, 'messages.json'),
+      JSON.stringify(composeMessages(enMessages, lang), null, 2)
+    );
+    count++;
+  }
+
+  logger.log(`Deployed locales to dist/_locales/: en${count ? ` + ${count} translation(s)` : ''}`);
+
+  // Complete
+  return complete();
+}
+
+// Translate config/messages.json message values — per-KEY incremental: only
+// strings without a cache entry (new or edited source) hit the provider.
+async function translateMessages(complete) {
+  // Only run in build mode
+  if (!Manager.isBuildMode()) {
+    logger.log('Skipping messages translation (not in build mode)');
+    return complete();
+  }
+
+  const settings = getSettings();
+  if (!settings.enabled) {
+    logger.log('Translation disabled (set translation.languages in omega.json5)');
+    return complete();
+  }
+
+  const enMessages = readConfigMessages();
+  if (!enMessages) {
+    logger.warn('config/messages.json not found or invalid, skipping');
+    return complete();
+  }
+
+  const brand = Manager.getConfig()?.brand?.name;
+  const limitsRules = Object.entries(LOCALE_LIMITS)
+    .map(([field, limit]) => `- The translation of the "${field}" message must be at most ${limit} characters (Chrome Web Store limit).`)
+    .join('\n');
+
+  let provider = null;
+
+  for (const lang of settings.languages) {
+    const cache = loadCache(translationsDir, lang, 'messages');
+    const sources = Object.values(enMessages).map((entry) => entry.message);
+    const misses = [...new Set(sources.filter((text) => cache[hashKey(text)] === undefined))];
+
+    if (!misses.length) {
+      logger.log(`[${lang}] All ${sources.length} messages cached`);
+      saveCache(translationsDir, lang, 'messages', cache, sources);
+      continue;
+    }
+
+    provider = provider || resolveProvider({ provider: settings.provider, model: settings.model });
+    logger.log(`[${lang}] Translating ${misses.length} message(s) (${provider.name}${provider.model ? `/${provider.model}` : ''})...`);
+
+    const { result } = await translateStrings({
+      strings: misses,
+      language: lang,
+      languageName: languageName(lang),
+      brand,
+      extraRules: limitsRules,
+      send: provider.send,
+    });
+
+    misses.forEach((text, i) => {
+      cache[hashKey(text)] = result[i];
+    });
+
+    // Warn on Chrome Web Store limit violations (keys sharing a message share a translation)
+    for (const [key, entry] of Object.entries(enMessages)) {
+      const limit = LOCALE_LIMITS[key];
+      const translated = cache[hashKey(entry.message)];
+
+      if (limit && translated && translated.length > limit) {
+        logger.warn(`[${lang}] "${key}" translation is ${translated.length} chars (limit ${limit}) — shorten it in translations/${lang}/messages.json`);
+      }
+    }
+
+    saveCache(translationsDir, lang, 'messages', cache, sources);
+    logger.log(`[${lang}] Messages translation saved`);
+  }
+
+  // Complete
+  return complete();
+}
+
+// Translate config/description.md per language — whole-document, cached as
+// committed markdown with a source-hash marker (edit the source → retranslate).
+async function translateDescription(complete) {
+  // Only run in build mode
+  if (!Manager.isBuildMode()) {
+    logger.log('Skipping description translation (not in build mode)');
+    return complete();
+  }
+
+  const settings = getSettings();
+  if (!settings.enabled) {
+    return complete();
+  }
+
+  if (!jetpack.exists(configDescriptionPath)) {
+    logger.log('config/description.md not found, skipping');
+    return complete();
+  }
+
+  const enDescription = jetpack.read(configDescriptionPath);
+  if (!enDescription || !enDescription.trim()) {
+    logger.warn('config/description.md is empty, skipping');
+    return complete();
+  }
+
+  const sourceHash = hashKey(enDescription);
+  const brand = Manager.getConfig()?.brand?.name;
+  let provider = null;
+
+  for (const lang of settings.languages) {
+    const outPath = path.join(translationsDir, lang, 'description.md');
+    const existing = jetpack.exists(outPath) ? jetpack.read(outPath) : null;
+
+    if (existing && existing.match(DESCRIPTION_MARKER)?.[1] === sourceHash) {
+      logger.log(`[${lang}] Description cached`);
+      continue;
+    }
+
+    provider = provider || resolveProvider({ provider: settings.provider, model: settings.model });
+    logger.log(`[${lang}] Translating description (${enDescription.length} chars)...`);
+
+    const { result } = await translateStrings({
+      strings: [enDescription],
+      language: lang,
+      languageName: languageName(lang),
+      brand,
+      extraRules: '- Preserve the markdown formatting (headers, bold, bullets) and keep all emojis exactly as they are.\n- Maintain the same tone — enthusiastic, conversational, and persuasive.',
+      send: provider.send,
+    });
+
+    jetpack.write(outPath, `<!-- omega:source ${sourceHash} -->\n${result[0]}`);
+    logger.log(`[${lang}] Description translation saved`);
+  }
+
+  // Complete
+  return complete();
+}
+
+/**
+ * Read a translated description (marker stripped) — used by the package task
+ * for store assets.
+ * @param {string} lang - language code
+ * @param {string} [baseDir] - translations dir override (tests)
+ * @returns {string|null}
+ */
+function readTranslatedDescription(lang, baseDir) {
+  const file = path.join(baseDir || translationsDir, lang, 'description.md');
+
+  if (!jetpack.exists(file)) {
+    return null;
+  }
+
+  return jetpack.read(file).replace(DESCRIPTION_MARKER, '');
+}
+
+// Export task
+module.exports = series(translateMessages, translateDescription, deployTranslations);
+module.exports.readTranslatedDescription = readTranslatedDescription;
+module.exports.composeMessages = composeMessages;

package/dist/gulp/tasks/utils/build-json.js

@@ -0,0 +1,43 @@
+// Read the OMEGA_BUILD_JSON snapshot back OUT of an emitted bundle.
+//
+// Since [#743](https://github.com/Omega-JS-Stack/omega/issues/743) the snapshot
+// is not a file any more — bundle.js's `buildJsonBanner` prepends a one-line
+// IIFE to every emitted bundle that assigns it onto globalThis/self/window, and
+// there is no `build.js` / `build.json` left to read. Anything that INSPECTS a
+// built artifact (the build-lane tests, the extension-auth e2e lane) needs the
+// same answer a browser gets, so it RUNS that banner the way a browser would
+// rather than regexing the text.
+
+const fs = require('fs');
+const vm = require('vm');
+
+/**
+ * The build snapshot an emitted bundle carries.
+ * @param {string} file - absolute path of an emitted `.bundle.js`
+ * @returns {object} the OMEGA_BUILD_JSON blob (`{ timestamp, repo, environment, license, packages, config }`)
+ * @throws {Error} when the file carries no bake — a bundle without one is a broken build, never a default
+ */
+function readBakedBuildJson(file) {
+  const banner = fs.readFileSync(file, 'utf8').split('\n', 1)[0];
+
+  // The banner is a self-contained IIFE with no imports and no browser APIs, so
+  // a bare context is all it needs — and `globalThis` inside the context IS the
+  // context, which is the same assignment a service worker's `self` receives.
+  const scope = {};
+  try {
+    vm.runInNewContext(banner, scope);
+  } catch (e) {
+    // A first line that is not the banner is the bundle's own code, which is
+    // neither self-contained nor runnable here — say what is actually wrong
+    // rather than handing back esbuild's output as a parse error.
+    throw new Error(`${file} carries no OMEGA_BUILD_JSON bake — its first line is not the bundle task's banner (${e.message})`);
+  }
+
+  if (!scope.OMEGA_BUILD_JSON) {
+    throw new Error(`${file} carries no OMEGA_BUILD_JSON bake — its first line assigned nothing (the bundle task's banner is missing)`);
+  }
+
+  return scope.OMEGA_BUILD_JSON;
+}
+
+module.exports = { readBakedBuildJson };

package/dist/gulp/tasks/utils/template-transform.js

@@ -0,0 +1,50 @@
+// Libraries
+const { Transform } = require('node:stream');
+const { template } = require('node-powertools');
+const path = require('path');
+
+/**
+ * Creates a transform stream that processes template variables in files
+ **/
+function createTemplateTransform(data) {
+  const extensions = ['html', 'md', 'liquid', 'json', 'yml', 'yaml']
+
+  return new Transform({
+    objectMode: true,
+    transform(file, encoding, callback) {
+      // Skip directories
+      if (file.isDirectory()) {
+        return callback(null, file);
+      }
+
+      // Check if file extension matches
+      const ext = path.extname(file.path).toLowerCase().slice(1);
+      if (!extensions.includes(ext)) {
+        return callback(null, file);
+      }
+
+      // Process the file contents
+      try {
+        const contents = file.contents.toString();
+
+        // Process templates
+        const templated = template(contents, data, {
+          brackets: ['[', ']'],
+        });
+
+        // Update file contents if changed
+        if (contents !== templated) {
+          file.contents = Buffer.from(templated);
+          const relativePath = file.relative || file.path;
+        }
+      } catch (error) {
+        console.error(`Error processing templates in ${file.path}:`, error);
+      }
+
+      // Pass the file through
+      callback(null, file);
+    },
+  });
+}
+
+module.exports = createTemplateTransform;

package/dist/gulp/templates/BUILD_INSTRUCTIONS.md

@@ -0,0 +1,69 @@
+# Build Instructions
+
+This document provides instructions for building the extension from source code.
+
+## System Requirements
+
+This extension was built on the following system:
+- **Operating System:** { system.platform } { system.release } ({ system.arch })
+- **Node.js Version:** { system.nodeVersion }
+
+## Prerequisites
+
+1. Install Node.js { system.nodeVersion } or compatible version
+2. Install npm (comes with Node.js)
+
+## Build Steps
+
+1. Extract the source code zip
+2. Open a terminal and navigate to the extracted directory
+3. Install dependencies:
+```sh
+npm install
+```
+4. Build the extension:
+```sh
+npm run build
+```
+5. The built extensions will be in `packaged/` directory:
+   - **Chrome/Edge/Brave:** `packaged/chromium/raw/` (unpacked) and `packaged/chromium/extension.zip`
+   - **Firefox:** `packaged/firefox/raw/` (unpacked) and `packaged/firefox/extension.zip`
+   - **Opera:** `packaged/opera/raw/` (unpacked) and `packaged/opera/extension.zip`
+
+## Loading the Extension
+
+### Chrome
+1. Go to `chrome://extensions`
+2. Enable "Developer mode"
+3. Click "Load unpacked"
+4. Select the `packaged/chromium/raw/` directory
+
+### Edge
+1. Go to `edge://extensions`
+2. Enable "Developer mode"
+3. Click "Load unpacked"
+4. Select the `packaged/chromium/raw/` directory
+
+### Firefox
+1. Go to `about:debugging`
+2. Click "This Firefox"
+3. Click "Load Temporary Add-on"
+4. Select `packaged/firefox/raw/manifest.json`
+
+### Opera
+1. Go to `opera://extensions`
+2. Enable "Developer mode"
+3. Click "Load unpacked"
+4. Select the `packaged/opera/raw/` directory
+
+### Brave
+1. Go to `brave://extensions`
+2. Enable "Developer mode"
+3. Click "Load unpacked"
+4. Select the `packaged/chromium/raw/` directory
+
+> **Note:** Brave is Chromium-based and uses the same build as Chrome/Edge. Extensions published to the Chrome Web Store are automatically available in Brave.
+
+## Questions
+
+If you have any questions about the build process, please contact the developer.

package/dist/index.js

@@ -0,0 +1,46 @@
+// // Libraries
+// const WebManager = require('@omega.js/client');
+
+// // Class
+// function Manager() {
+//   const self = this;
+
+//   // Properties
+//   self.extension = null;
+//   self.messenger = null;
+//   self.logger = null;
+//   self.omega = null;
+
+//   // Return
+//   return self;
+// }
+
+// Manager.prototype.initialize = function (callback) {
+//   const self = this;
+
+//   // Configuration
+//   const configuration = window.OMEGA_BUILD_JSON?.config;
+
+//   // Initiate the web manager
+//   self.extension = require('./lib/extension');
+//   self.messenger = null;
+//   self.logger = new (require('./lib/logger-lite'))('popup');
+//   self.omega = new WebManager();
+
+//   // Initialize
+//   self.omega.init(configuration, callback);
+
+//   // Return
+//   return self.omega;
+// };
+
+// Manager.prototype.library = function (name) {
+//   const self = this;
+
+//   // Return
+//   return require(`./lib/${name}`);
+// };
+
+
+// // Export
+// module.exports = Manager;