@omega.js/extension 0.1.0

package/dist/build.js

@@ -0,0 +1,268 @@
+// Libraries
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const fs = require('fs');
+const JSON5 = require('json5');
+const argv = require('yargs')(process.argv.slice(2)).parseSync();
+const { spawn } = require('child_process');
+const { force } = require('node-powertools');
+
+// Class
+function Manager() {
+  const self = this;
+
+  // Properties
+  self._logger = null;
+
+  // Return
+  return self;
+}
+
+// Initialize
+Manager.prototype.initialize = function () {
+  console.log('initialize:');
+};
+
+// Logger
+Manager.prototype.logger = function (name) {
+  // Check if called as static method (this is not a Manager instance)
+  if (!(this instanceof Manager)) {
+    // For static calls, just return a new logger without caching
+    return new (require('./lib/logger'))(name);
+  }
+
+  // For instance calls, cache the logger
+  if (!this._logger) {
+    this._logger = new (require('./lib/logger'))(name);
+  }
+
+  return this._logger;
+};
+
+// argv
+Manager.getArguments = function () {
+  const options = argv || {};
+
+  // Fix
+  options._ = options._ || [];
+  // browser can be: true (all), false (none), or a string like 'chrome' or 'chrome,firefox'
+  options.browser = options.browser === undefined ? true : options.browser;
+  options.debug = force(options.debug === undefined ? false : options.debug, 'boolean');
+
+  // Return
+  return options;
+};
+Manager.prototype.getArguments = Manager.getArguments;
+
+// The notifly argv for a build error. Build messages routinely carry apostrophes
+// and parentheses, so the message is a spawn ARG — never interpolated into a shell
+// string, which mangled it and killed the notification (#104).
+Manager.getBuildErrorNotificationArgs = function (plugin, message) {
+  return [
+    '--title', `Build Error: ${plugin}`,
+    '--message', message,
+    '--timeout', '3',
+    '--sound', 'Sosumi',
+  ];
+};
+
+// notifly is an optional local nicety, so a MISSING BINARY is one friendly note —
+// never the raw `spawn notifly ENOENT` dump that used to land after a suite (#123).
+// Every other spawn failure keeps the logged-not-thrown error path from #104.
+Manager.reportNotificationFailure = function (error) {
+  const logger = new (require('./lib/logger'))('build-error');
+
+  if (error && error.code === 'ENOENT') {
+    return logger.warn('notifly not installed — skipping desktop notification');
+  }
+
+  return logger.error('Failed to send notification', error);
+};
+Manager.prototype.reportNotificationFailure = Manager.reportNotificationFailure;
+
+// Report build errors with notification
+Manager.reportBuildError = function (error, callback) {
+  const logger = new (require('./lib/logger'))('build-error');
+
+  // Send notification using notifly
+  const errorMessage = error.message || error.toString() || 'Unknown error';
+  const errorPlugin = error.plugin || 'Build';
+
+  spawn('notifly', Manager.getBuildErrorNotificationArgs(errorPlugin, errorMessage), { shell: false, stdio: 'ignore' })
+    .on('error', (e) => Manager.reportNotificationFailure(e));
+
+  // Log the error
+  logger.error(`[${errorPlugin}] ${errorMessage}`);
+
+  // If callback provided, call it with error
+  if (callback) {
+    return callback(error);
+  }
+
+  // Otherwise return a function that calls the callback with error
+  return (cb) => cb ? cb(error) : error;
+};
+Manager.prototype.reportBuildError = Manager.reportBuildError;
+
+// isBuildMode: checks if the build mode is enabled
+Manager.isBuildMode = function () {
+  return process.env.OMEGA_BUILD_MODE === 'true';
+}
+Manager.prototype.isBuildMode = Manager.isBuildMode;
+
+// actLikeProduction - determines if we should act like production mode
+Manager.actLikeProduction = function () {
+  return Boolean(Manager.isBuildMode() || process.env.OMEGA_AUDIT_FORCE === 'true');
+}
+Manager.prototype.actLikeProduction = Manager.actLikeProduction;
+
+// getEnvironment() is the SSOT and lives in src/utils/mode-helpers.js (alongside the is*()
+// family). It's mixed onto the Manager via the attachTo() call below, same as in EM/UJM.
+
+// getManifest: requires and parses config.yml
+Manager.getManifest = function () {
+  return JSON5.parse(jetpack.read('src/manifest.json') || '{}');
+}
+Manager.prototype.getManifest = Manager.getManifest;
+
+// getConfig: the consumer's RESOLVED config/omega.json5 via @omega.js/config —
+// shared sections at the top level, targets.extension overlaid onto them (brand
+// walk-up applies in brand monorepos). Secrets never live in the file; the loader
+// hard-fails on secret-shaped keys.
+Manager.getConfig = function () {
+  const { hasOmegaConfig, loadConfig, formatErrors } = require('./vendor/config/index.js');
+
+  // No config at all (fresh dir, non-consumer cwd) → empty shape; callers
+  // optional-chain and the defaults task scaffolds the real file on setup.
+  const cwd = process.cwd();
+  if (!hasOmegaConfig(cwd)) {
+    return {};
+  }
+
+  const { config, errors } = loadConfig(cwd, 'extension');
+
+  // Validation findings are FATAL at build time — same contract as the web
+  // build's loadSiteData ([#426](https://github.com/Omega-JS-Stack/omega/issues/426)).
+  // A retired key reads as nothing at all, so a build that only warned shipped
+  // a bundle missing whatever lived under it and still exited 0. Thrown on
+  // EVERY call, never warn-once: tasks call this at require time, and a
+  // once-per-process flag left calls 2..n silently building on the bad config.
+  if (errors.length) {
+    throw new Error(`[@omega.js/extension] config/omega.json5 is invalid:\n${formatErrors(errors)}`);
+  }
+
+  return config;
+}
+Manager.prototype.getConfig = Manager.getConfig;
+
+// getPackage: requires and parses package.json
+Manager.getPackage = function (type) {
+  const basePath = type === 'project'
+    ? process.cwd()
+    : path.resolve(__dirname, '..')
+
+  const pkgPath = path.join(basePath, 'package.json')
+  return JSON5.parse(jetpack.read(pkgPath))
+}
+Manager.prototype.getPackage = Manager.getPackage;
+
+// getRootPath: returns the root path of the project or package
+Manager.getRootPath = function (type) {
+  return type === 'project'
+    ? process.cwd()
+    : path.resolve(__dirname, '..')
+}
+Manager.prototype.getRootPath = Manager.getRootPath;
+
+// getLiveReloadPort: (35729)
+Manager.getLiveReloadPort = function () {
+  // Check if the port is set in the environment
+  process.env.OMEGA_LIVERELOAD_PORT = process.env.OMEGA_LIVERELOAD_PORT || 35729;
+
+  // Return the port
+  return parseInt(process.env.OMEGA_LIVERELOAD_PORT);
+}
+Manager.prototype.getLiveReloadPort = Manager.getLiveReloadPort;
+
+// getDevWebsiteOrigin: where the brand's dev website answers (protocol + port),
+// as the live sibling website app published it beside its port map. An extension
+// has no way to probe at runtime, so every dev-origin surface — the build.js
+// blob, the page config blob, the manifest's externally_connectable — BAKES this
+// one answer ([#262](https://github.com/Omega-JS-Stack/omega/issues/262)).
+//
+// null when nothing published one: presence is a RESOLVED FACT, absence means
+// "assume the classics" and say so (the N7 dev-map contract). A packaged build
+// never probes at all — its artifact must not depend on whether a dev server
+// happened to be running on the build machine.
+Manager.getDevWebsiteOrigin = function () {
+  const { readSiblingOrigin } = require('./vendor/config/index.js');
+
+  if (Manager.getEnvironment() === 'production') {
+    return null;
+  }
+
+  return readSiblingOrigin(Manager.getRootPath('project'));
+}
+Manager.prototype.getDevWebsiteOrigin = Manager.getDevWebsiteOrigin;
+
+// Create dummy file in project dist to force jekyll to build
+Manager.triggerRebuild = function (files, logger) {
+  // Ensure logger is defined
+  logger = this?._logger || logger || console;
+
+  // Normalize files into an array of file names
+  if (typeof files === 'string') {
+    files = [files]; // Single string file name
+  } else if (Array.isArray(files)) {
+    // Already an array, no changes needed
+  } else if (typeof files === 'object' && files !== null) {
+    files = Object.keys(files); // Extract keys from object
+  } else {
+    logger.error('Invalid files for triggerRebuild()');
+    return;
+  }
+
+  // Set current time
+  const now = new Date();
+
+  // Touch all files to update mtime (so Jekyll notices)
+  files.forEach((file) => {
+    try {
+      fs.utimesSync(file, now, now);
+      logger.log(`Triggered build: ${file}`);
+    } catch (e) {
+      logger.error(`Failed to trigger build ${file}`, e);
+    }
+  });
+}
+Manager.prototype.triggerRebuild = Manager.triggerRebuild;
+
+// Require
+Manager.require = function (path) {
+  return require(path);
+};
+Manager.prototype.require = Manager.require;
+
+// Memory monitoring utility
+Manager.getMemoryUsage = function () {
+  const used = process.memoryUsage();
+  return {
+    rss: Math.round(used.rss / 1024 / 1024),
+    heapTotal: Math.round(used.heapTotal / 1024 / 1024),
+    heapUsed: Math.round(used.heapUsed / 1024 / 1024),
+    external: Math.round(used.external / 1024 / 1024),
+  };
+};
+Manager.prototype.getMemoryUsage = Manager.getMemoryUsage;
+
+Manager.logMemory = function (logger, label) {
+  const mem = Manager.getMemoryUsage();
+  logger.log(`[Memory ${label}] RSS: ${mem.rss}MB | Heap Used: ${mem.heapUsed}MB / ${mem.heapTotal}MB | External: ${mem.external}MB`);
+};
+Manager.prototype.logMemory = Manager.logMemory;
+
+// Cross-context helpers — Manager.isTesting() / isDevelopment() / etc.
+require('./utils/mode-helpers.js').attachTo(Manager);
+
+// Export
+module.exports = Manager;

package/dist/cli-run.js

@@ -0,0 +1,25 @@
+/**
+ * run() — the omega-extension bin body, shared by bin/omega-extension (via
+ * dist/omega-bin.js) and cross-framework dispatch ('@omega.js/extension/cli').
+ */
+async function run() {
+  // Local-dist freshness guard: a stale locally-linked dist rebuilds and the
+  // invocation re-execs once, so no command ever runs stale framework code
+  require('./vendor/devkit/local.js').freshnessBoot({ packageName: '@omega.js/extension' });
+
+  // Value-less flags must be declared boolean — otherwise yargs treats the next
+  // positional as the flag's VALUE. Mirrors the same fix in @omega.js/backend's CLI.
+  // yargs' built-in --version/--help are disabled so both route through the
+  // alias table / the router's built-in help (the built-ins printed an empty
+  // stub and version "0.0.0" — yargs can't resolve our package version here).
+  const argv = require('yargs')(process.argv.slice(2))
+    .boolean(['extended'])
+    .version(false)
+    .help(false)
+    .parseSync();
+  const cli = new (require('./cli.js'))(argv);
+
+  await cli.process(argv);
+}
+
+module.exports = { run };

package/dist/cli.js

@@ -0,0 +1,30 @@
+// Libraries
+const path = require('path');
+const { createCliRouter } = require('./vendor/devkit/cli-router.js');
+
+// Resolve the .env cascade from the project root
+// (shell > local .env > brand .env > company .env). The target name delivers
+// the schema's `deliverAs` renames into process.env (#678) — the brand's
+// GOOGLE_ANALYTICS_SECRET_EXTENSION arrives as GOOGLE_ANALYTICS_SECRET.
+require('./vendor/config/index.js').loadEnv(process.cwd(), { target: 'extension' });
+
+// Main class — dispatch (positional/flag alias resolution, command loading,
+// error surfacing) is the shared devkit router; this file owns only the alias
+// table and the commands directory.
+//
+// A bare `omega` prints help: setup is retired and every verb runs the local
+// scaffold itself ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+module.exports = createCliRouter({
+  commandsDir: path.join(__dirname, 'commands'),
+  defaultCommand: 'help',
+  aliases: {
+    build: ['-b', '--build'],
+    clean: ['-c', '--clean'],
+    deploy: ['-d', '--deploy'],
+    install: ['-i', 'i', '--install'],
+    migrate: ['-m', '--migrate', 'migration'],
+    test: ['-t', '--test'],
+    update: ['-u', '--update', 'outdated', 'out'],
+    version: ['-v', '--version'],
+  },
+});

package/dist/commands/build.js

@@ -0,0 +1,67 @@
+// Libraries
+const { execute } = require('node-powertools');
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('build');
+const { ensureTarget } = require('./lib/ensure-target.js');
+
+// The consumer's `build` script is `omega build` — this verb owns the pipeline
+// and the build-mode flag; it must never shell back to that script (that would
+// recurse). `npm run gulp -- <task>` is the one safe shell-out: the consumer's
+// `gulp` script is bare `gulp`, so there's no alias to recurse through. The
+// gulp `build` series does no cleaning of its own, so the verb owns that step
+// too. Desktop runs the same model through utils/build-pipeline.js because
+// three verbs share it there; extension has the one plan, so it lives here.
+function plan() {
+  return {
+    env: { OMEGA_BUILD_MODE: 'true' },
+    steps: [
+      { type: 'clean' },
+      { type: 'gulp', task: 'build' },
+    ],
+  };
+}
+
+// Step implementations — the seam runPlan takes as an argument, so a test can
+// record the order without running a real gulp build.
+const RUNNERS = {
+  clean: (options) => require('./clean.js')(options),
+  gulp: (options, step) => execute(`npm run gulp -- ${step.task}`, { log: true }),
+};
+
+async function runPlan(plan, options, runners) {
+  options = options || {};
+  runners = runners || RUNNERS;
+
+  // Set in-process so every child (gulp → esbuild → the packager) inherits them.
+  Object.entries(plan.env || {}).forEach(([key, value]) => {
+    process.env[key] = value;
+  });
+
+  for (const step of plan.steps) {
+    const runner = runners[step.type];
+
+    // The plan is authored in this file alongside the runner table — an unknown
+    // step type is a programmer error, never consumer input.
+    if (!runner) {
+      throw new Error(`Unknown pipeline step type: ${step.type}`);
+    }
+
+    await runner(options, step);
+  }
+}
+
+module.exports = async function (options) {
+  // Log
+  logger.log('Running production build...');
+
+  // The local scaffold BEFORE the pipeline (#675): the gulp `defaults` task
+  // ensures too, but gulp itself is one of the peer deps the ensure installs,
+  // so a fresh consumer outside any node_modules hoist never reaches it.
+  await ensureTarget({ log: (line) => logger.log(line), warn: (line) => logger.warn(line) });
+
+  await runPlan(plan(options), options);
+};
+
+module.exports.plan = plan;
+module.exports.runPlan = runPlan;
+module.exports.RUNNERS = RUNNERS;

package/dist/commands/clean.js

@@ -0,0 +1,29 @@
+// Libraries
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('clean');
+const { cleanDirs } = require('../vendor/devkit/clean-dirs.js');
+const { ensureTarget } = require('./lib/ensure-target.js');
+
+// Dirs to clean
+const dirs = [
+  '.temp',
+  'dist',
+  'packaged',
+  // 'src/assets/themes',
+]
+
+module.exports = async function (options) {
+  // The local scaffold (#675): the consumer `start` and `build` scripts are
+  // `omega clean && … npm run gulp …`, and gulp itself is one of the peer
+  // deps the ensure installs — clean is the only verb that runs before it.
+  await ensureTarget({ log: (line) => logger.log(line), warn: (line) => logger.warn(line) });
+
+  // Log
+  logger.log(`Cleaning up .temp, dist, and packaged directories...`);
+
+  try {
+    cleanDirs(dirs);
+  } catch (e) {
+    logger.error(`Error clearing directories: ${e}`);
+  }
+};

package/dist/commands/deploy.js

@@ -0,0 +1,97 @@
+/**
+ * `omega deploy` — the explicit publish verb (D13: commits never
+ * auto-publish). Syncs the working tree (commit + push — push triggers
+ * NOTHING), then dispatches the scaffolded publish workflow: CI builds,
+ * uploads to the stores when credentials are present, and attaches the
+ * package zip to a GitHub release (the durable artifact channel).
+ *
+ * Every run starts with the local scaffold the retired `omega setup` used to
+ * own (ensureTarget, #675) and then runs setup's NETWORK half as a precheck
+ * before the dispatch. `--no-secrets` skips that precheck.
+ *
+ * Flags: --dry-run (print the exact dispatch, send nothing; skips sync),
+ * --no-sync (dispatch without committing/pushing first).
+ */
+const { execSync } = require('node:child_process');
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('deploy');
+const { deployViaDispatch, dispatchRepo, findLocalSpecs, syncWorkingTree } = require('../vendor/devkit/deploy.js');
+const { composedWorkflowName } = require('../vendor/devkit/ci-workflows.js');
+const { resolveSeedMode } = require('../vendor/config/index.js');
+const { ensureTarget } = require('./lib/ensure-target.js');
+const { deployPrecheck } = require('./lib/deploy-precheck.js');
+
+module.exports = async function (options) {
+  options = options || {};
+  const dryRun = options.dryRun || options['dry-run'];
+  const projectDir = process.cwd();
+
+  // The local half of the retired `omega setup` (#675) — idempotent, offline,
+  // and quiet on a converged target.
+  await ensureTarget({ projectDir, log: (line) => logger.log(line), warn: (line) => logger.warn(line) });
+
+  // The NETWORK half, as a precheck: a deploy is the verb that needs the
+  // remote side right. A dry run sends nothing, so it prechecks nothing.
+  if (!dryRun) {
+    await deployPrecheck({ projectDir, options, logger });
+  }
+
+  // Inside a brand monorepo the target's CI lives in the BRAND ROOT's workflows
+  // dir under a per-target name (#265) — dispatch what setup actually composed.
+  const WORKFLOW = composedWorkflowName({
+    targetDir: process.cwd(),
+    brandRoot: resolveSeedMode(process.cwd()).brandRoot,
+    workflow: 'publish.yml',
+  });
+
+  // Linked local packages (tree-wide file: specs — cp194) → the LOCAL lane
+  // automatically: build + store-publish from this machine with the linked
+  // frameworks bundled in. Mirrored rule (Ian 2026-07-20); CI dispatch is
+  // only for registry-clean trees.
+  if (findLocalSpecs({ dir: process.cwd() }).length > 0) {
+    logger.log('Linked local packages detected — building + publishing LOCALLY (linked frameworks bundled; store credentials must be available in this shell). CI dispatch resumes after `omega i live`.');
+    if (dryRun) {
+      logger.log('DRY RUN — would run: npm run release (local build + store publish)');
+      return;
+    }
+    execSync('npm run release', { stdio: 'inherit' });
+    require('../vendor/devkit/deploy-record.js').recordDeploy({ dir: process.cwd(), target: 'extension', detail: { method: 'local' } });
+    return logger.log('Deployed from the LOCAL build (linked frameworks included).');
+  }
+
+  if (!dryRun && options.sync !== false) {
+    logger.log('Syncing (commit + push — publishes nothing by itself)...');
+    syncWorkingTree({ message: 'Deploy', logger });
+  }
+
+  const { owner, repo } = dispatchAddress();
+  const { plan, dispatched } = await deployViaDispatch({ workflow: WORKFLOW, owner, repo, dryRun });
+
+  if (dispatched) {
+    require('../vendor/devkit/deploy-record.js').recordDeploy({ dir: process.cwd(), target: 'extension', detail: { method: 'dispatch' } });
+    logger.log(`Dispatched ${WORKFLOW} — CI builds, publishes to stores, and attaches the zip to a GitHub release.`);
+    logger.log(`Watch: ${plan.runsUrl}`);
+  } else {
+    logger.log('DRY RUN — would send:');
+    logger.log(`  ${plan.method} ${plan.url}`);
+    logger.log(`  body: ${JSON.stringify(plan.body)}`);
+    logger.log(`  then watch: ${plan.runsUrl}`);
+  }
+};
+
+/**
+ * The repo this target's CI dispatch addresses: the brand's own, from its
+ * config ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)). A git
+ * remote answers the repo the working tree SITS IN, which inside a brand nested
+ * in another repo is the enclosing one, so the dispatch went to a workflow that
+ * was never there. The rule is `@omega.js/devkit/deploy`'s `dispatchRepo`, the
+ * same call web's deploy and desktop's release verbs make. Exported for tests.
+ *
+ * @returns {{ owner: string, repo: string }} owner and bare repo name
+ * @throws {Error} when the config names no repo
+ */
+function dispatchAddress() {
+  return dispatchRepo(Manager.getConfig());
+}
+
+module.exports.dispatchAddress = dispatchAddress;

package/dist/commands/install.js

@@ -0,0 +1,58 @@
+// Libraries
+const Manager = new (require('../build.js'));
+const logger = Manager.logger('install');
+const { safeInstall } = require('../lib/safe-install');
+const local = require('../vendor/devkit/local.js');
+
+// Load package
+const package = Manager.getPackage('main');
+const project = Manager.getPackage('project');
+
+module.exports = async function (options) {
+  // Log
+  logger.log(`Installing ${package.name}...`);
+
+  // Get type
+  const type = options._[1] || 'prod';
+
+  try {
+    // Install production — the publish-day inverse of `i local`: flip every
+    // file: spec in the brand tree to the exact <linked version>, one registry install
+    if (['live', 'prod', 'p', 'production'].includes(type)) {
+      // Log
+      logger.log('Installing production (restoring registry specs tree-wide)...');
+
+      // Restore
+      const actions = await local.restoreRegistrySpecs({ dir: process.cwd(), logger });
+      const flipped = actions.filter((action) => action.action === 'flip').length;
+
+      // Return
+      return logger.log(flipped > 0
+        ? `Production installation complete (${flipped} spec(s) restored to registry ranges).`
+        : 'Already on registry specs — nothing to flip.');
+    }
+
+    // Install development (link from the local Omega monorepo)
+    if (['dev', 'd', 'development', 'local', 'l'].includes(type)) {
+      // Log
+      logger.log('Installing development (local Omega monorepo)...');
+
+      // Link every @omega.js dependency to the monorepo (idempotent)
+      await local.linkLocalPackages({
+        dir: process.cwd(),
+        monorepoRoot: local.resolveMonorepoRoot(),
+        logger,
+      });
+
+      // Return
+      return logger.log('Development installation complete.');
+    }
+
+  } catch (e) {
+    logger.error(`Error during install:`, e);
+  }
+};
+
+function install(command) {
+  return safeInstall(command);
+}

package/dist/commands/lib/dependencies.js

@@ -0,0 +1,33 @@
+/**
+ * @omega.js/extension's half of the shared dependency checks
+ * ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)) — the logic is
+ * `@omega.js/devkit/target-dependencies` (one copy for every framework); this
+ * file is the DATA: which peer deps install as devDependencies, and the
+ * framework's own `safeInstall`.
+ *
+ *   ensurePeerDependencies  the target cannot build without them — LOCAL half,
+ *                           ensure-target.js runs it on every verb
+ *   updateManager           asks the npm registry whether the framework itself
+ *                           is stale — NETWORK half, deploy-precheck.js runs it
+ */
+const shared = require('../../vendor/devkit/target-dependencies.js');
+const { safeInstall } = require('../../lib/safe-install');
+
+// Peer-dep install location overrides
+const DEPENDENCY_MAP = {
+  'gulp': 'dev',
+};
+
+const readProject = shared.readProject;
+
+/** See `@omega.js/devkit/target-dependencies` — bound to the extension's map + installer. */
+function ensurePeerDependencies(input) {
+  return shared.ensurePeerDependencies({ ...input, dependencyMap: DEPENDENCY_MAP, safeInstall });
+}
+
+/** See `@omega.js/devkit/target-dependencies` — bound to the extension's installer. */
+function updateManager(input) {
+  return shared.updateManager({ ...input, safeInstall });
+}
+
+module.exports = { ensurePeerDependencies, updateManager, readProject, DEPENDENCY_MAP };

package/dist/commands/lib/deploy-precheck.js

@@ -0,0 +1,57 @@
+/**
+ * deploy-precheck — the NETWORK half `omega setup` used to own
+ * ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)).
+ *
+ * Setup's local half now rides every verb (ensure-target.js); what needs the
+ * network rides the ONE verb that needs the remote side right —
+ * `omega deploy` — as a precheck before the dispatch:
+ *
+ *   framework-freshness  the npm registry's latest vs the installed version,
+ *                        since CI builds this deploy with whatever the
+ *                        manifest pins
+ *   push-secrets         the composed target env → GitHub Actions repo secrets,
+ *                        which the dispatched workflow's generated env block
+ *                        consumes ([#680](https://github.com/Omega-JS-Stack/omega/issues/680))
+ *
+ * Every step is soft: a precheck reports, the deploy proceeds. `--no-secrets`
+ * skips the whole precheck — the same opt-out name on web, desktop and
+ * extension (parity).
+ *
+ * The RUNNER is `@omega.js/devkit/deploy-precheck` (one copy for every
+ * framework); this file is the extension's STEPS.
+ */
+const Manager = new (require('../../build.js'));
+const { runDeployPrecheck } = require('../../vendor/devkit/deploy-precheck.js');
+const { updateManager } = require('./dependencies.js');
+const { publishEnvSecrets } = require('./push-secrets.js');
+
+const package = Manager.getPackage('main');
+
+/**
+ * The default steps, in order. Named so a test can hand its own recorder in
+ * and read back exactly which ones ran.
+ */
+const STEPS = [
+  {
+    name: 'framework-freshness',
+    run: ({ projectDir, log, warn }) => updateManager({ projectDir, package, log, error: warn }),
+  },
+  {
+    name: 'push-secrets',
+    run: ({ projectDir, log, warn }) => publishEnvSecrets({ targetDir: projectDir, logger: { log, warn, error: warn } }),
+  },
+];
+
+/**
+ * @param {object} input
+ * @param {string} input.projectDir - The target root.
+ * @param {object} input.options - The parsed CLI options (`secrets: false` = opted out).
+ * @param {object} input.logger - `{ log, warn, error }`.
+ * @param {Array} [input.steps] - Injectable step list (tests).
+ * @returns {Promise<{ skipped: string }|{ ran: string[] }>} The steps that ran, or the opt-out marker.
+ */
+function deployPrecheck({ projectDir, options, logger, steps }) {
+  return runDeployPrecheck({ projectDir, options, logger, steps: steps || STEPS });
+}
+
+module.exports = { deployPrecheck, STEPS };