@omega.js/extension 0.1.0

package/dist/commands/lib/ensure-target.js

@@ -0,0 +1,151 @@
+/**
+ * ensure-target — the LOCAL, idempotent scaffold every verb runs
+ * ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+ *
+ * `omega setup` used to own this half and nothing ran it for you, so a target
+ * drifted until someone remembered the command per target. It is retired: the
+ * "write it if missing" steps live here, the gulp `defaults` task calls it
+ * first (so `npm start` and every gulp build heal the tree), and the non-gulp
+ * verbs — `omega test`, `omega deploy` — call it themselves.
+ *
+ * What it guarantees, in this order:
+ *
+ *   package.json      the omega verb scripts + the npm-private latch — pure
+ *                     manifest edits, so they land before anything that throws
+ *   node version      FATAL when the shell is older than the framework's pin
+ *   peer dependencies installed when missing or behind (a satisfied target
+ *                     installs nothing)
+ *   defaults tree     the consumer interior, via the gulp defaults task's
+ *                     scaffoldDefaults — the ONE scaffold implementation
+ *   locality          a WARNING when the framework is a `file:` link
+ *
+ * What needs the network is NOT here: the framework freshness check is an
+ * `omega deploy` precheck (deploy-precheck.js), and the one-time hook-layout
+ * migration is its own command (`omega migrate`).
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const version = require('wonderful-version');
+const Manager = new (require('../../build.js'));
+const { ensurePeerDependencies, readProject } = require('./dependencies.js');
+const { assertScaffoldable } = require('../../vendor/devkit/scaffold-guard.js');
+
+const logger = Manager.logger('ensure-target');
+const package = Manager.getPackage('main');
+
+/**
+ * Sync the consumer manifest: the omega verb scripts and the npm-private latch
+ * (extensions are never published to npm). Identical content is not a write
+ * (#572) — it matters more since #675, because this runs on EVERY verb.
+ */
+function setupScripts(projectDir, result) {
+  projectDir = projectDir || Manager.getRootPath('project');
+  result = result || { changed: [] };
+
+  const project = readProject(projectDir);
+
+  // Setup the scripts
+  project.scripts = project.scripts || {};
+
+  Object.keys(package.projectScripts).forEach((key) => {
+    project.scripts[key] = package.projectScripts[key];
+  });
+
+  // Ensure the project is private (extensions should never be published to npm)
+  project.private = true;
+
+  // Save the project — npm's own shape, trailing newline included.
+  const projectPath = path.join(projectDir, 'package.json');
+  const contents = `${JSON.stringify(project, null, 2)}\n`;
+
+  if (jetpack.read(projectPath) === contents) {
+    return;
+  }
+
+  jetpack.write(projectPath, contents);
+  result.changed.push('package.json (scripts + private)');
+}
+
+/** The framework's pinned runtime is a FLOOR here — an older shell is fatal. */
+function ensureNodeVersion(log) {
+  const installedVersion = version.clean(process.version);
+  const requiredVersion = version.clean(package.omega.nodeRuntime);
+  const isUpToDate = version.is(installedVersion, '>=', requiredVersion);
+
+  log(`Checking if Node.js is up to date (${logger.format.bold(installedVersion)} >= ${logger.format.bold(requiredVersion)}): ${isUpToDate ? logger.format.green('Yes') : logger.format.red('No')}`);
+
+  if (!isUpToDate) {
+    throw new Error(`Node version is out-of-date. Required version is ${requiredVersion}.`);
+  }
+}
+
+/** Warn when the framework is a `file:` link — that install never publishes. */
+function checkLocality(projectDir, warn) {
+  const project = readProject(projectDir);
+  const installedVersion = project.devDependencies[package.name] || project.dependencies[package.name];
+
+  if (!installedVersion) {
+    throw new Error(`No installed version of ${package.name} found in dependencies or devDependencies.`);
+  }
+
+  if (installedVersion.startsWith('file:')) {
+    warn(`⚠️⚠️⚠️ You are using the local version of ${package.name}. This WILL NOT WORK when published. ⚠️⚠️⚠️`);
+  }
+}
+
+/**
+ * Make the target whole — idempotent, offline, and quiet when there is
+ * nothing to do.
+ *
+ * @param {object} [options]
+ * @param {string} [options.projectDir] - The target root (default: cwd).
+ * @param {function} [options.log] - Line logger (silent by default).
+ * @param {function} [options.warn] - Warning logger (silent by default).
+ * @returns {Promise<{ written: string[], merged: string[], changed: string[] }>}
+ *   Target-relative paths per outcome — empty on a no-op run.
+ */
+async function ensureTarget(options) {
+  options = options || {};
+  const projectDir = options.projectDir || Manager.getRootPath('project');
+  const log = options.log || (() => {});
+  const warn = options.warn || (() => {});
+  const result = { written: [], merged: [], changed: [] };
+
+  // The framework's own tree is not a consumer target. Running the framework's
+  // suite from packages/extension puts the framework at the cwd, and a verb
+  // that scaffolds unconditionally would install its own peer deps into itself
+  // and scatter the consumer defaults through the package. Refuse, quietly:
+  // this is a normal state, not a broken one.
+  if (readProject(projectDir).name === package.name) {
+    return result;
+  }
+
+  // A workspace ROOT is not a target either — and unlike the case above, landing
+  // there is an accident (a verb run from the wrong cwd), so it fails LOUD (#699).
+  assertScaffoldable(projectDir);
+
+  setupScripts(projectDir, result);
+  ensureNodeVersion(log);
+
+  await ensurePeerDependencies({ projectDir, package, log });
+
+  // The consumer interior — the SAME engine run the build's defaults task
+  // performs (friction #13). Required lazily: that task requires this module
+  // back, and only one of the two can win at load time.
+  const { scaffoldDefaults } = require('../../gulp/tasks/defaults.js');
+  const applied = scaffoldDefaults({ outputDir: projectDir });
+  if (applied) {
+    result.written.push(...applied.written);
+    result.merged.push(...applied.merged);
+  }
+
+  checkLocality(projectDir, warn);
+
+  for (const [label, files] of [['Created', result.written], ['Merged', result.merged], ['Synced', result.changed]]) {
+    if (files.length > 0) log(`${label} ${files.join(', ')}`);
+  }
+
+  return result;
+}
+
+module.exports = { ensureTarget, setupScripts };

package/dist/commands/lib/push-secrets.js

@@ -0,0 +1,60 @@
+/**
+ * The `.env` → GitHub Actions secrets publisher for the extension target
+ * ([#680](https://github.com/Omega-JS-Stack/omega/issues/680)).
+ *
+ * The publish workflow is dispatched with no `.env` on the runner, so every
+ * store credential and the baked Measurement Protocol secret reach the build
+ * as repo Actions secrets — and until now nothing PUT them there: a consumer
+ * pasted each one into the GitHub UI by hand, and a fresh brand's first publish
+ * failed on whichever one they missed. `omega deploy` now pushes them, exactly
+ * as web does.
+ *
+ * "Exactly as web does" is now literal: the derive → collect → guard → publish
+ * orchestration is `@omega.js/devkit/target-secrets`, and this file is the
+ * BIND — the target string and nothing else. Extension secrets are plain
+ * strings, so there is no file/base64 lane here; that is desktop's, for its
+ * signing certificates.
+ */
+const { collectTargetSecrets, declaredBrandRepo: declaredRepoFor, publishTargetSecrets } = require('../../vendor/devkit/target-secrets.js');
+
+const TARGET = 'extension';
+
+/**
+ * The publishable secrets: the schema's extension delivery set, valued from
+ * the composed env. An empty value never claims a key.
+ *
+ * @param {string} targetDir - The target root (its .env is the local layer).
+ * @returns {Object<string, string>} key → value, ready to publish.
+ */
+function collectEnvSecrets(targetDir) {
+  return collectTargetSecrets({ targetDir, target: TARGET });
+}
+
+/**
+ * The brand's OWN repo as `owner/name`, from the composed config. Null when
+ * the config declares nothing usable or doesn't load.
+ *
+ * @param {string} targetDir - The target root.
+ * @returns {string|null}
+ */
+function declaredBrandRepo(targetDir) {
+  return declaredRepoFor({ targetDir, target: TARGET });
+}
+
+/**
+ * The `omega deploy` precheck step: publish the target's composed values as
+ * repo Actions secrets.
+ *
+ * @param {object} options
+ * @param {string} options.targetDir - The target root.
+ * @param {object} options.logger - `{ log, warn, error }`.
+ * @param {object} [options.env] - Env map (default: process.env).
+ * @param {function} [options.execFn] - Injectable `gh` exec (tests).
+ * @param {function} [options.gitExecFn] - Injectable `git` exec for remote discovery (tests).
+ * @returns {{ skipped: string }|{ published: string[], failed: Array<object> }}
+ */
+function publishEnvSecrets(options) {
+  return publishTargetSecrets({ ...(options || {}), target: TARGET });
+}
+
+module.exports = { collectEnvSecrets, declaredBrandRepo, publishEnvSecrets };

package/dist/commands/migrate.js

@@ -0,0 +1,77 @@
+/**
+ * `omega migrate` — the one-time, version-gated moves an upgrade needs.
+ *
+ * This used to be step one of `omega setup` and ran on every setup. Setup is
+ * retired ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)) and its
+ * local half now runs on every verb, which is the wrong home for a migration:
+ * a MOVE is not idempotent healing, it is a one-time upgrade step a consumer
+ * runs deliberately (the same shape `@omega.js/web` already ships).
+ *
+ * Today it carries one migration: hook files moved to the nested layout in
+ * 2.0.0. A `file:` install is skipped — a linked consumer is already current.
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const version = require('wonderful-version');
+const Manager = new (require('../build.js'));
+const { readProject } = require('./lib/dependencies.js');
+
+const logger = Manager.logger('migrate');
+const package = Manager.getPackage('main');
+
+// Old hook file name → its new nested path
+const HOOK_MIGRATIONS = [
+  { old: 'build:post.js', new: 'build/post.js' },
+  { old: 'build:pre.js', new: 'build/pre.js' },
+  { old: 'middleware:request.js', new: 'middleware/request.js' },
+];
+
+/** Move old flat hook files into the nested structure (introduced in 2.0.0). */
+function migrateHooksToNestedStructure(projectDir) {
+  const hooksDir = path.join(projectDir, 'hooks');
+  let migratedCount = 0;
+
+  for (const migration of HOOK_MIGRATIONS) {
+    const oldPath = path.join(hooksDir, migration.old);
+    const newPath = path.join(hooksDir, migration.new);
+
+    if (!jetpack.exists(oldPath)) {
+      continue;
+    }
+
+    if (jetpack.exists(newPath)) {
+      logger.warn(`⚠️  Migrate ${migration.old}: ${migration.new} already exists`);
+    }
+
+    jetpack.move(oldPath, newPath, { overwrite: true });
+    logger.log(`✅ Migrated hook: ${migration.old} → ${migration.new}`);
+    migratedCount++;
+  }
+
+  if (migratedCount > 0) {
+    logger.log(`✅ Migrated ${migratedCount} hook file(s) to new nested structure`);
+  }
+
+  return migratedCount;
+}
+
+module.exports = async function (options) {
+  options = options || {};
+
+  const projectDir = options.projectDir || Manager.getRootPath('project');
+  const project = readProject(projectDir);
+  const installedVersion = project.devDependencies[package.name] || project.dependencies[package.name] || '0.0.0';
+
+  // A linked consumer builds from THIS source — there is nothing to migrate to.
+  if (installedVersion.startsWith('file:')) {
+    return logger.log('Local (`file:`) install — nothing to migrate.');
+  }
+
+  if (version.is(installedVersion, '<=', '2.0.0')) {
+    migrateHooksToNestedStructure(projectDir);
+  }
+
+  logger.log('Migration complete');
+};
+
+module.exports.migrateHooksToNestedStructure = migrateHooksToNestedStructure;

package/dist/commands/test.js

@@ -0,0 +1,110 @@
+// Libraries
+const path    = require('path');
+const fs      = require('fs');
+const Manager = new (require('../build.js'));
+const logger  = Manager.logger('test');
+const { run } = require('../test/runner.js');
+const attachLogFile = require('../utils/attach-log-file.js');
+const { EXTENDED_MODE_WARNING } = require('../test/utils/extended-mode-warning.js');
+const { noMatchMessage, noMatchExitCode } = require('../vendor/devkit/test/scope.js');
+const { ensureTarget } = require('./lib/ensure-target.js');
+
+module.exports = async function (options) {
+  // Tee all test output to <projectRoot>/logs/test.log (ANSI-stripped) — mirrors
+  // EM's test.log and @omega.js/backend's test.log pattern.
+  attachLogFile(path.join(process.cwd(), 'logs', 'test.log'));
+
+  // The local half of the retired `omega setup` (#675) — idempotent, offline,
+  // and quiet on a converged target. The gulp verbs get it from the `defaults`
+  // task; test runs no gulp, so it calls it here.
+  await ensureTarget({
+    projectDir: process.cwd(),
+    log: (line) => logger.log(line),
+    warn: (line) => logger.warn(line),
+  });
+
+  const layer       = options.layer    || 'all';
+  // Positional target: `npx omega test <target>` where target supports source
+  // prefixes — `project:`, `project:<path>`, `mgr:`, `extension:`, or a bare `<path>`.
+  const target      = (options._ && options._[1]) || null;
+  // `--filter` flag: substring match on test NAMES/descriptions (orthogonal to target).
+  const filter      = options.filter   || null;
+  const reporter    = options.reporter || 'pretty';
+  // Extended mode — opt into tests that hit REAL external services (Firebase via @omega.js/client,
+  // push, any network call) instead of skipping them. Off by default so `npx omega test` stays
+  // fast and offline-safe. The canonical signal is the unprefixed `TEST_EXTENDED_MODE` env var
+  // — the SAME name across @omega.js/backend/BXM/UJM/EM (cross-framework parity); `--extended` is the CLI
+  // shorthand. Once set on process.env it propagates to every spawned test environment (the
+  // in-process Node runner, and Puppeteer's Chromium which inherits process.env).
+  const extended    = options.extended === true
+    || options.extended === 'true'
+    || process.env.TEST_EXTENDED_MODE === 'true'
+    || process.env.TEST_EXTENDED_MODE === '1';
+
+  if (extended) {
+    process.env.TEST_EXTENDED_MODE = 'true';
+  }
+
+  // Canonical signal — every Manager picks this up via isTesting().
+  process.env.OMEGA_TEST_MODE = 'true';
+
+  // When BXM itself runs its own boot-layer tests (the cwd's package.json is
+  // BXM's package.json), there's no real consumer extension to target. Point
+  // the boot runner at the fixture under dist/test/fixtures/consumer-extension
+  // unless the caller has already set OMEGA_TEST_BOOT_PROJECT explicitly.
+  if (!process.env.OMEGA_TEST_BOOT_PROJECT) {
+    try {
+      const cwdPkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+      if (cwdPkg.name === '@omega.js/extension') {
+        process.env.OMEGA_TEST_BOOT_PROJECT = path.join(__dirname, '..', 'test', 'fixtures', 'consumer-extension');
+      }
+    } catch (_) { /* no package.json — leave unset */ }
+  }
+
+  if (reporter !== 'json') {
+    logger.log(`Running tests (layer=${layer}${target ? ` target="${target}"` : ''}${filter ? ` filter="${filter}"` : ''}${extended ? ' +extended' : ''})`);
+    logger.log(`Test mode: ${extended ? 'extended (real external APIs)' : 'normal (external APIs skipped)'}`);
+    if (extended) {
+      logger.warn(EXTENDED_MODE_WARNING[0]);
+      EXTENDED_MODE_WARNING.slice(1).forEach((line) => logger.warn(line));
+    }
+  }
+
+  const result = await run({ layer, target, filter, reporter });
+
+  if (reporter === 'json') {
+    // Final machine-readable summary.
+    process.stdout.write(`${JSON.stringify({
+      event:   'summary',
+      passed:  result.passed,
+      failed:  result.failed,
+      skipped: result.skipped,
+      total:   result.passed + result.failed + result.skipped,
+    })}\n`);
+  }
+
+  // A target that named files and matched none is a failed run, not an empty
+  // one: a typo'd path, or a suite renamed out from under it, used to report
+  // "0 passing" and exit 0
+  // ([#814](https://github.com/Omega-JS-Stack/omega/issues/814)).
+  if (result.noMatch) {
+    logger.error(noMatchMessage(result.noMatch));
+    // Standalone that is 1. Inside a brand-root fan-out the manager forwarded
+    // ONE target to every target, so a distinct code lets it count this as a
+    // miss rather than a failure (#814).
+    process.exitCode = noMatchExitCode();
+    await attachLogFile.detach();
+    return;
+  }
+
+  if (result.failed > 0) {
+    process.exitCode = 1;
+    await attachLogFile.detach();
+    throw new Error(`${result.failed} test(s) failed`);
+  }
+
+  // Close test.log and restore stdout/stderr. Nothing to flush: every write
+  // already went to the fd synchronously (#197), so detach() just closes the
+  // handle — the Results block is on disk before this line runs.
+  await attachLogFile.detach();
+};

package/dist/commands/update.js

@@ -0,0 +1,21 @@
+/**
+ * `omega update` — dependency freshness report (npu-outdated semantics):
+ * installed/wanted/latest + patch/minor/major per dep, releases younger than
+ * --min-age days (default 7) QUARANTINED. `--apply` installs the
+ * non-quarantined, non-breaking set (`--major` opts into breaking) through
+ * npu when present. The whole verb is the shared devkit implementation.
+ */
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('update');
+const { runUpdate } = require('../vendor/devkit/update.js');
+
+module.exports = async function (options) {
+  await runUpdate({
+    dir: process.cwd(),
+    apply: options.apply,
+    major: options.major,
+    minAge: options.minAge ?? options['min-age'],
+    forceFresh: options.forceFresh || options['force-fresh'],
+    logger,
+  });
+};

package/dist/commands/version.js

@@ -0,0 +1,12 @@
+// Libraries
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('version');
+
+// Load package
+const package = Manager.getPackage('main');
+const project = Manager.getPackage('project');
+
+module.exports = async function (options) {
+  // Log
+  logger.log(package.version);
+};

package/dist/config/manifest.json

@@ -0,0 +1,117 @@
+{
+  // Basic info
+  manifest_version: 3,
+  name: '__MSG_appName__',
+  short_name: '__MSG_appNameShort__',
+  description: '__MSG_appDescription__',
+
+  // Icon
+  icons: {
+    '1024': 'assets/images/icons/icon-1024x.png',
+    '512': 'assets/images/icons/icon-512x.png',
+    '256': 'assets/images/icons/icon-256x.png',
+    '128': 'assets/images/icons/icon-128x.png',
+    '64': 'assets/images/icons/icon-64x.png',
+    '48': 'assets/images/icons/icon-48x.png',
+    '32': 'assets/images/icons/icon-32x.png',
+    '24': 'assets/images/icons/icon-24x.png',
+    '16': 'assets/images/icons/icon-16x.png',
+  },
+
+  // Default locale
+  default_locale: 'en',
+
+  // Background script
+  // Chrome uses service_worker, Firefox uses scripts array
+  background: {
+    service_worker: 'assets/js/components/background.bundle.js',
+    scripts: ['assets/js/components/background.bundle.js'],
+  },
+
+  // Permissions
+  permissions: [
+  ],
+  host_permissions: [
+  ],
+
+  // Options page
+  options_ui: {
+    page: 'views/options/index.html',
+  },
+
+  // Content scripts
+  content_scripts: [
+  ],
+
+  // Browser action
+  action: {
+    // default_icon: {
+    //   '48': 'assets/images/icons/icon-48x.png',
+    //   '32': 'assets/images/icons/icon-32x.png',
+    //   '24': 'assets/images/icons/icon-24x.png',
+    //   '16': 'assets/images/icons/icon-16x.png',
+    // },
+    default_icon: 'assets/images/icons/icon-48x.png',
+    default_title: '__MSG_appName__',
+    // default_popup: '', // Disabled so we can customize what happens on click
+  },
+
+  // Side panel
+  side_panel: {
+    default_path: 'views/sidepanel/index.html',
+  },
+
+  // Content security policy
+  content_security_policy: {
+    extension_pages: "script-src 'self'; object-src 'self'; worker-src 'self';",
+  },
+
+  // Web accessible resources
+  // Origins allowed to message this extension. BUILD-TIME-BAKED by design (N7
+  // non-goal: a shipped extension can't probe ports), and RESOLVED at package
+  // time, never a literal: the brand's own origin (from `brand.url`) always,
+  // plus the live sibling website's dev origin — protocol and port both, the
+  // classic https://localhost:4000 when nothing is running — in dev only. A
+  // packaged build used to ship the localhost origin alone, so the brand site
+  // could not message the published extension (#583). If your `omega dev`
+  // bumped, rebuild while it's running (or pin `ports.website` in the brand
+  // config) so both sides agree.
+  externally_connectable: {
+    matches: [
+      %%%externallyConnectableOrigins%%%
+    ],
+  },
+
+  // Web accessible resources
+  web_accessible_resources: [
+  ],
+
+  // Offscreen document (for persistent background operations like WebSocket)
+  // offscreen_document: {
+  //   file: 'views/offscreen/index.html',
+  // },
+
+  // Commands
+  commands: {
+  },
+
+  // Sandbox
+  sandbox: {
+    pages: [
+    ],
+  },
+
+  // IDs
+  browser_specific_settings: {
+    gecko: {
+      // id: 'my-addon@example.com',
+      strict_min_version: '91.0',
+      // Required for new Firefox extensions as of Nov 2025
+      // https://blog.mozilla.org/addons/2025/10/23/data-collection-consent-changes-for-new-firefox-extensions/
+      data_collection_permissions: {
+        required: ['authenticationInfo'],
+        optional: ['technicalAndInteraction'],
+      },
+    },
+  },
+}

package/dist/config/page-template.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html data-bs-theme="{{ theme.appearance }}">
+  <head>
+    <!-- Meta -->
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <title>{{ page.title }}</title>
+
+    <!-- Main CSS (includes Font Awesome) -->
+    <link href="/assets/css/main.bundle.css?cb={{ cacheBust }}" rel="stylesheet">
+
+    <!-- Component-specific CSS -->
+    <link href="/assets/css/components/{{ page.name }}.bundle.css?cb={{ cacheBust }}" rel="stylesheet">
+  </head>
+  <body>
+    {{ content }}
+
+    <!-- Main JS (OMEGA_BUILD_JSON rides baked in the bundle's banner, #743) -->
+    <script src="/assets/js/components/{{ page.name }}.bundle.js?cb={{ cacheBust }}"></script>
+  </body>
+</html>

package/dist/content.js

@@ -0,0 +1,37 @@
+// Libraries
+import extension from './lib/extension.js';
+import LoggerLite from './lib/logger-lite.js';
+import Messaging from './lib/messaging.js';
+import Affiliatizer from './lib/affiliatizer.js';
+import { attachTo as attachModeHelpers } from './utils/mode-helpers.js';
+
+// Class
+class Manager {
+  constructor() {
+    // Properties
+    this.extension = null;
+    this.messenger = null;
+    this.logger = null;
+    this.affiliatizer = null;
+  }
+
+  async initialize() {
+    // Set properties
+    this.extension = extension;
+    this.messenger = new Messaging({ sender: 'content' });
+    this.logger = new LoggerLite('content');
+    this.affiliatizer = Affiliatizer.initialize(this);
+
+    // Log
+    this.logger.log('Initialized!', this);
+
+    // Return manager instance
+    return this;
+  }
+}
+
+// Cross-context helpers — Manager.isTesting() / isDevelopment() / etc.
+attachModeHelpers(Manager);
+
+// Export
+export default Manager;