@omega.js/extension 0.1.0

package/dist/vendor/devkit/omega-bin.js

@@ -0,0 +1,345 @@
+/**
+ * omega-bin — the context-aware dispatcher behind every framework's `omega`/`omg` bin.
+ *
+ * Problem: every OMEGA framework ships the same bin names (`omega`, `omg`, `mgr`).
+ * In a brand monorepo with several targets, npm hoists all of them to the brand root
+ * and only ONE framework's file wins the node_modules/.bin link — so the bin that
+ * actually runs is arbitrary. This module makes any winner correct: it resolves
+ * the context that owns the CALLER'S cwd — nearest first, walking up — and runs
+ * THAT context's CLI:
+ *
+ *   - an OMEGA PACKAGE'S OWN ROOT (package.json `name` is `@omega.js/*`) →
+ *     that package's own CLI, or a refusal when it ships none. Checked FIRST,
+ *     ahead of the dependency rule: a framework devDepends on other frameworks
+ *     (extension and desktop on @omega.js/web for vendorAssets, the manager on
+ *     @omega.js/backend), and reading those as a target made `omega test` in
+ *     packages/extension run WEB's CLI, which scaffolded a web target into the
+ *     package ([#757](https://github.com/Omega-JS-Stack/omega/issues/757))
+ *   - a TARGET (nearest package.json declaring a framework, including the
+ *     backend's functions/ layout) → that framework's CLI
+ *   - a BRAND ROOT (config/omega.json5 with no framework declared nearer)
+ *     → @omega.js/manager's CLI, so `omega test` at a brand root fans out
+ *     over the brand's targets instead of guessing one framework
+ *
+ * Contract: every dispatch target exposes `exports['./cli']` → a module with
+ * `run()` that parses process.argv itself. Framework bin shims call
+ * `run({ hostName, hostRun })` — hostRun executes the host's own CLI via a
+ * RELATIVE require (vendor-safe), so the host never resolves itself by name.
+ *
+ * This module stays stdlib-only (fs/path/module): it is vendored into every
+ * framework dist and must never assume another package is installed.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { createRequire } = require('module');
+
+const FRAMEWORKS = [
+  '@omega.js/web',
+  '@omega.js/backend',
+  '@omega.js/desktop',
+  '@omega.js/extension',
+];
+
+const MANAGER = '@omega.js/manager';
+
+// Every package in the OMEGA monorepo carries this name prefix; no consumer
+// target ever does. A manifest with it IS the package, never a project built
+// on top of one (#757).
+const OMEGA_SCOPE = '@omega.js/';
+
+// Dirs that are a VIEW of the target one level up, never a context of their own:
+// a backend's runtime cwd (functions/) and its staged build output (dist/,
+// which carries a COMPOSED config/omega.json5 that would otherwise read as a
+// brand root). Stdlib twin of @omega.js/config's TARGET_SUBDIRS — that module is
+// the canonical list ([#307](https://github.com/Omega-JS-Stack/omega/issues/307)).
+const TARGET_SUBDIRS = ['functions', 'dist'];
+
+// The only verbs allowed to run with NO target context. The fallback exists for
+// the bootstrap case (`npx omega onboard` in a fresh clone, #276) and for verbs
+// that only READ; every other verb runs its target scaffold first (#675), so a
+// run in a directory that owns no target WRITES one there — that is how a stray
+// `omega deploy` at a workspace root scaffolded a whole desktop target into it
+// ([#699](https://github.com/Omega-JS-Stack/omega/issues/699)).
+//
+// Tokens, not command names: a flag-style alias (`omega --deploy`, `omega -v`)
+// selects a verb too, so every spelling of an allowed verb is listed —
+// onboard/help/version across the router frameworks and the manager, plus
+// backend's `cwd` and desktop's `logs`, the two read-only reporters.
+const CONTEXTLESS_VERBS = new Set([
+  'onboard', 'create', 'new', '-o', '--onboard',
+  'help', 'h', '-h', '--help',
+  'version', 'v', '-v', '--version',
+  'cwd',
+  'logs', 'log', '--logs', 'logs:read', 'logs:tail', 'logs:stream',
+]);
+
+// The signing box's verbs. A box that hosts the Windows EV signing runner is a
+// MACHINE, not a project: `omega runner` and `omega sign-windows` read their
+// configuration from the runner home and run from any directory. Both belong
+// to @omega.js/desktop, so with no target they go to desktop's CLI — the host
+// when desktop won the bin link (a bare `npm i -g @omega.js/desktop`), else
+// desktop resolved from the cwd (a monorepo checkout, a brand root) — and
+// refuse naming the install when it is nowhere. They scaffold nothing
+// ([#337](https://github.com/Omega-JS-Stack/omega/issues/337)).
+const BOX_VERBS = new Set(['runner', 'sign-windows']);
+const DESKTOP = '@omega.js/desktop';
+
+/**
+ * The signing-box verb this invocation selects, or null. The ONE reading of
+ * "is this the box's", shared by the dispatcher below and by
+ * @omega.js/desktop's CLI (which skips the project `.env` cascade for exactly
+ * these) — two readings would drift, and the drift is a brand's token reaching
+ * the box.
+ *
+ * Both spellings count: the bare token (`omega runner status`) and the `--`
+ * flag desktop's alias table takes (`omega --runner`, `omega --sign-windows
+ * --smoke`). `--help` is never one: it prints help, in every spelling. A box
+ * verb sitting in an ARGUMENT position is not one either — `omega test runner`
+ * runs the test verb — so the first positional has to be the box verb itself.
+ *
+ * @param {string[]} argv - Arguments after the bin name.
+ * @returns {string|null} The box verb's canonical name, or null.
+ */
+function boxVerbOf(argv) {
+  argv = argv || [];
+  if (argv.includes('--help') || argv.includes('-h')) return null;
+
+  const positional = argv.find((arg) => !arg.startsWith('-'));
+  if (positional && BOX_VERBS.has(positional)) return positional;
+
+  const flag = argv.find((arg) => arg.startsWith('--') && BOX_VERBS.has(arg.slice(2)));
+  return flag ? flag.slice(2) : null;
+}
+
+/**
+ * Boolean half of boxVerbOf — what callers that only need the yes/no ask.
+ *
+ * @param {string[]} argv - Arguments after the bin name.
+ * @returns {boolean}
+ */
+function isBoxVerbArgv(argv) {
+  return boxVerbOf(argv) !== null;
+}
+
+function readPackage(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+function frameworksOf(pkg) {
+  if (!pkg) return [];
+  const declared = Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {});
+  return FRAMEWORKS.filter((name) => declared[name]);
+}
+
+/**
+ * Is `dir` a brand-monorepo root? Carries a config/omega.json5 that is not
+ * itself a TARGET_SUBDIR view (functions/, dist/) and not a TARGET of a brand above
+ * it (directly under a targets/ dir whose parent also carries a brand config).
+ * Stdlib twin of @omega.js/config's resolveBrandRoot rule — that module is the
+ * canonical definition; this copy exists because the dispatcher cannot depend
+ * on @omega.js/config.
+ */
+function isBrandRoot(dir) {
+  if (TARGET_SUBDIRS.includes(path.basename(path.resolve(dir)))) return false;
+  if (!fs.existsSync(path.join(dir, 'config', 'omega.json5'))) return false;
+
+  const parent = path.dirname(dir);
+  const isTargetOfBrand = path.basename(parent) === 'targets'
+    && fs.existsSync(path.join(path.dirname(parent), 'config', 'omega.json5'));
+
+  return !isTargetOfBrand;
+}
+
+/**
+ * Walk up from startDir to the nearest dispatch context. At each level, in
+ * order: the dir's own package.json being an OMEGA package, then declaring a
+ * framework, then brand-root-ness. IDENTITY beats dependency — a framework
+ * devDepends on other frameworks, and reading those as a target dispatched a
+ * framework's own root to a sibling framework's CLI (#757). Framework checks
+ * then come before the brand check so a standalone consumer (framework dep AND
+ * its own config/omega.json5 in one dir) dispatches as a target, not a brand.
+ * The CLI entry normalizes a functions/ cwd up to the target root
+ * (muscle-memory `cd functions` still works).
+ *
+ * The walk is BOUNDED at the nearest `.git` (that directory is still checked
+ * first): past the repo boundary is somebody else's tree, never this dir's
+ * dispatch context. Same bound as @omega.js/config's resolveBrandRoot and the
+ * Claude plugin's inject hook.
+ *
+ * @returns {{ kind: 'self', name: string, dir: string }
+ *   | { kind: 'framework', name: string, dir: string }
+ *   | { kind: 'brand', dir: string } | null} dir = the package's own root
+ *   (self) / where the framework dep is declared (framework) / the brand root
+ *   (brand)
+ */
+function findTarget(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    const pkg = readPackage(dir);
+
+    if (pkg && typeof pkg.name === 'string' && pkg.name.startsWith(OMEGA_SCOPE)) {
+      return { kind: 'self', name: pkg.name, dir };
+    }
+
+    const matches = frameworksOf(pkg);
+    if (matches.length > 1) {
+      // Targets are one-framework-per-target by design — a multi-framework
+      // manifest dispatches by FRAMEWORKS order, which must never be silent.
+      console.error(`omega: ${dir} declares ${matches.length} frameworks (${matches.join(', ')}) — dispatching ${matches[0]}`);
+    }
+    const own = matches[0] || null;
+    if (own) return { kind: 'framework', name: own, dir };
+
+    if (isBrandRoot(dir)) {
+      return { kind: 'brand', dir };
+    }
+
+    // Repo boundary — stop here rather than statting out through the host
+    // filesystem to /.
+    if (fs.existsSync(path.join(dir, '.git'))) return null;
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Resolve a dispatch target's ./cli from where it is declared.
+ * @returns {{ cliPath: string } | { error: Error }} — callers decide whether an
+ *   unresolvable target is fatal (cross-framework) or falls back (brand).
+ */
+function tryResolveCli(name, fromDir) {
+  const req = createRequire(path.join(fromDir, 'package.json'));
+  try {
+    return { cliPath: req.resolve(`${name}/cli`) };
+  } catch (e) {
+    return { error: e };
+  }
+}
+
+/** Resolve a dispatch target's ./cli from where it is declared, with a clear failure. */
+function resolveCli(name, fromDir, hint) {
+  const { cliPath, error } = tryResolveCli(name, fromDir);
+  if (error) {
+    console.error(`omega: found ${name} context (${fromDir}) but could not resolve '${name}/cli': ${error.message}`);
+    console.error(hint);
+    process.exit(1);
+  }
+  return cliPath;
+}
+
+/**
+ * The verb an invocation resolves to, as far as the dispatcher can see it: the
+ * frameworks' own resolution rules minus their per-framework alias tables.
+ * `--help`/`-h` wins outright (cli-router routes it ahead of positionals, so
+ * `omega deploy --help` prints help), then the first positional token, then the
+ * first flag-style alias. A bare `omega` has no verb — every CLI defaults to help.
+ *
+ * @param {string[]} argv - Arguments after the bin name.
+ * @returns {string|null} The selecting token, or null for a bare invocation.
+ */
+function verbOf(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return 'help';
+  return argv.find((arg) => !arg.startsWith('-')) || argv[0] || null;
+}
+
+async function run({ hostName, hostRun, argv = process.argv.slice(2) }) {
+  const target = findTarget(process.cwd());
+
+  // No context — the bootstrap case (a verb run in a fresh directory has
+  // no framework dep yet, by definition). Run the HOST framework's CLI, exactly
+  // like the pre-dispatcher bins did, and say which one so a hoist-winner at a
+  // brand root is never a silent mystery.
+  if (!target) {
+    // …but ONLY for a verb that cannot write. The fallback hands a mutating verb
+    // to whichever framework won npm's bin link, and that verb scaffolds its own
+    // target into the cwd — a directory that owns no target is never where that
+    // should land (#699). Twin of ensure-target's refusal (devkit scaffold-guard.js).
+    const verb = verbOf(argv);
+    const boxVerb = boxVerbOf(argv);
+    if (boxVerb) {
+      if (hostName === DESKTOP) return hostRun();
+      const { cliPath } = tryResolveCli(DESKTOP, process.cwd());
+      if (!cliPath) {
+        console.error(`omega: "${boxVerb}" is ${DESKTOP}'s — a signing box runs it from any directory, but ${DESKTOP} is not installed here (from ${process.cwd()}). \`npm i -g ${DESKTOP}\`, then run it again.`);
+        process.exit(1);
+      }
+      console.error(`omega: no target context found from ${process.cwd()} — "${boxVerb}" is a signing-box verb, running ${DESKTOP}`);
+      return require(cliPath).run();
+    }
+    if (verb && !CONTEXTLESS_VERBS.has(verb)) {
+      console.error(`omega: refusing to run "${verb}" — ${process.cwd()} is not inside an OMEGA target (no framework dependency and no config/omega.json5 above it). Nothing was scaffolded.`);
+      console.error('Run it from a target directory, or `npx omega onboard` to create one here. Without a target, only onboard (create, new), help, version, cwd and logs run; the signing box\'s runner and sign-windows run through @omega.js/desktop.');
+      process.exit(1);
+    }
+
+    console.error(`omega: no target context found from ${process.cwd()} — running ${hostName}`);
+    return hostRun();
+  }
+
+  // An OMEGA package's OWN root — run ITS CLI, so `omega test` in
+  // packages/extension runs the extension's self-test. A package is never a
+  // target: nothing here may reach the host fallback, whose ensure-target would
+  // scaffold a consumer project into the framework source tree (#757).
+  if (target.kind === 'self') {
+    if (target.name === hostName) return hostRun();
+
+    const { cliPath, error } = tryResolveCli(target.name, target.dir);
+    if (!cliPath) {
+      // Two different facts share one refusal: a package that exports no
+      // `./cli` at all (config, devkit, ...) versus one that declares it but
+      // cannot resolve it right now (an unbuilt dist, a fresh clone before
+      // `npm install`). Name the one that applies.
+      const reason = error && error.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED'
+        ? 'which ships no CLI'
+        : `whose './cli' did not resolve (${error ? error.message : 'unknown'}; an unbuilt dist? run its prepare)`;
+      console.error(`omega: refusing to run — ${target.dir} is the ${target.name} package itself, ${reason}, and an OMEGA package is never a target. Nothing was scaffolded.`);
+      process.exit(1);
+    }
+    return require(cliPath).run();
+  }
+
+  // A brand root — the manager owns brand-level commands (`omega test` fans
+  // out over targets/*). Resolve it from the brand root and hand over.
+  if (target.kind === 'brand') {
+    const { cliPath } = tryResolveCli(MANAGER, target.dir);
+
+    // Brand-SHAPED is not always a brand: every verb's ensureTarget scaffolds
+    // config/omega.json5 into a standalone project before its framework dep lands
+    // in package.json, so the walk classifies a fresh target as a brand root. With
+    // no manager installed there is no brand-level CLI to hand over to — fall
+    // back to the host framework rather than dead-ending (#194). A real brand
+    // root still dispatches to the manager the moment it exists.
+    if (!cliPath) {
+      // When the HOST is the manager itself (its own bin in a fresh template
+      // clone), "install the manager" would name the thing about to run —
+      // that message is for framework hosts only.
+      if (hostName === MANAGER) {
+        console.error(`omega: brand-shaped directory at ${target.dir} with no installed ${MANAGER} — running the bundled ${hostName} (run npm install to use the pinned version)`);
+      } else {
+        console.error(`omega: brand-shaped directory at ${target.dir} but ${MANAGER} is not installed — running ${hostName} instead (install ${MANAGER} at the brand root, or \`mgr i local\` for a monorepo link, if this really is a brand)`);
+      }
+      return hostRun();
+    }
+    return require(cliPath).run();
+  }
+
+  // The bin that won npm's .bin link belongs to this target's framework — run it directly.
+  if (target.name === hostName) {
+    return hostRun();
+  }
+
+  // The target belongs to a DIFFERENT framework — resolve its CLI from where the
+  // dependency is declared and hand over.
+  const cliPath = resolveCli(target.name, target.dir,
+    'Is the framework installed? Try npm install, or `mgr i local` for a monorepo link.');
+  return require(cliPath).run();
+}
+
+module.exports = { run, findTarget, isBrandRoot, verbOf, isBoxVerbArgv, TARGET_SUBDIRS, CONTEXTLESS_VERBS, BOX_VERBS, FRAMEWORKS, MANAGER };

package/dist/vendor/devkit/safe-install.js

@@ -0,0 +1,18 @@
+// safeInstall(command) — run a shell command, routing `npm install` through Socket
+// Firewall (sfw) when it's available so dependency trees are scanned for malware,
+// typosquats, and supply-chain attacks before download. Non-install commands and
+// machines without sfw pass through unchanged.
+
+const { execute } = require('node-powertools');
+
+let _hasSfw;
+async function safeInstall(command, options) {
+  if (_hasSfw === undefined) {
+    _hasSfw = await execute('sfw --version', { log: false }).then(() => true).catch(() => false);
+  }
+  const isInstall = /^npm\s+(install|i)\b/.test(command);
+  const prefix = (_hasSfw && isInstall) ? 'sfw ' : '';
+  return execute(`${prefix}${command}`, options || { log: true });
+}
+
+module.exports = { safeInstall };

package/dist/vendor/devkit/scaffold-guard.js

@@ -0,0 +1,96 @@
+/**
+ * scaffold-guard — the refusal every framework's ensure-target runs before it
+ * writes anything.
+ *
+ * Every verb heals its target on the way past ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)),
+ * which makes the cwd load-bearing: `omega deploy` run at a workspace ROOT
+ * scaffolded a whole desktop target into it — gulpfile, src/, workflows, rewritten
+ * root scripts — before failing anyway ([#699](https://github.com/Omega-JS-Stack/omega/issues/699)).
+ * A workspace root is never a target: a target is a MEMBER of one. So a scaffold
+ * aimed at a manifest declaring `workspaces` is a misfire, not a fresh project.
+ *
+ * Twin of the dispatcher's own refusal (`@omega.js/devkit/omega-bin`), one layer
+ * lower and same shape: that one catches a verb run where NO context resolves,
+ * this one catches a verb that reached a framework CLI anyway. Throwing is the
+ * loud stop — every framework CLI prints the message and exits nonzero.
+ *
+ * Stdlib-only (fs/path), like the dispatcher: it is vendored into every framework
+ * dist and runs before the framework's own dependencies matter.
+ */
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * The nearest package.json walking up from startDir, BOUNDED at the nearest
+ * `.git` (that directory is still checked) — past the repo boundary is somebody
+ * else's tree. Same bound as the dispatcher's findTarget.
+ *
+ * @param {string} startDir - Where to start the walk.
+ * @returns {{ dir: string, manifestPath: string }|null} null when nothing is found.
+ */
+function nearestManifest(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    const manifestPath = path.join(dir, 'package.json');
+    if (fs.existsSync(manifestPath)) return { dir, manifestPath };
+
+    if (fs.existsSync(path.join(dir, '.git'))) return null;
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * A refusal: crafted text a human is meant to read, flagged so every surface
+ * prints it the same way — the message alone, nothing added. `@omega.js/backend`'s
+ * bin and devkit's cli-router both branch on the flag, so a refused command
+ * never renders as a bug (a red ✗ there, a raw stack here) ([#706](https://github.com/Omega-JS-Stack/omega/issues/706)).
+ *
+ * @param {string} message - The lines to print verbatim.
+ * @returns {Error} The flagged error to throw.
+ */
+function refusal(message) {
+  const error = new Error(message);
+  error.refusal = true;
+  return error;
+}
+
+/**
+ * Throw unless projectDir can legitimately be scaffolded as a target. A fresh
+ * directory with no manifest above it stays allowed — that is the standalone
+ * bootstrap case every verb supports.
+ *
+ * @param {string} projectDir - The directory ensure-target is about to write to.
+ * @returns {void}
+ * @throws {Error} When the nearest manifest declares `workspaces`, or cannot be read.
+ */
+function assertScaffoldable(projectDir) {
+  const nearest = nearestManifest(projectDir);
+  if (!nearest) return;
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(nearest.manifestPath, 'utf8'));
+  } catch (e) {
+    // Unreadable is not "not a workspace root". Scaffolding on that guess is the
+    // exact accident this guard exists to stop, so it refuses — and names the
+    // file, which a raw SyntaxError out of JSON.parse never did.
+    throw refusal(
+      `omega: refusing to scaffold into ${path.resolve(projectDir)} — ${nearest.manifestPath} could not be read `
+      + `(${e.message}), so whether this is a workspace root cannot be known. Nothing was scaffolded.\n`
+      + 'Fix that manifest, or run the verb from inside a target (e.g. targets/<name>).',
+    );
+  }
+
+  if (!manifest.workspaces) return;
+
+  throw refusal(
+    `omega: refusing to scaffold into ${path.resolve(projectDir)} — ${nearest.manifestPath} declares "workspaces", `
+    + 'so this is a workspace root (a brand or monorepo root), not an OMEGA target. Nothing was scaffolded.\n'
+    + 'Run the verb from inside a target (e.g. targets/<name>), or `npx omega onboard` to create one.',
+  );
+}
+
+module.exports = { assertScaffoldable, nearestManifest };

package/dist/vendor/devkit/strip-dev-blocks-plugin.js

@@ -0,0 +1,29 @@
+/**
+ * esbuild plugin form of the `@dev-only` strip (#18, #736).
+ *
+ * A thin binding to the ONE cut in `strip-dev-blocks.js` (the webpack loader
+ * twin was deleted with the last webpack lane in
+ * [#738](https://github.com/Omega-JS-Stack/omega/issues/738)), and
+ * unconditional — the lane that registers the plugin decides WHEN. `bundle.js`
+ * registers it for production builds only, so a dev build keeps its warnings
+ * and simulation hooks.
+ */
+
+const fs = require('node:fs');
+
+const { stripDevBlocks, START_MARKER } = require('./strip-dev-blocks.js');
+
+const stripDevBlocksPlugin = {
+  name: 'omega-strip-dev-blocks',
+  setup(build) {
+    build.onLoad({ filter: /\.js$/ }, (args) => {
+      const source = fs.readFileSync(args.path, 'utf8');
+      if (!source.includes(START_MARKER)) {
+        return null; // untouched — let esbuild load it normally
+      }
+      return { contents: stripDevBlocks(source), loader: 'js' };
+    });
+  },
+};
+
+module.exports = { stripDevBlocksPlugin };

package/dist/vendor/devkit/strip-dev-blocks.js

@@ -0,0 +1,32 @@
+/**
+ * The `@dev-only` marker contract — ONE home (#18).
+ *
+ * Code between the markers runs in development and is cut out of every
+ * PRODUCTION bundle, so dev warnings and simulation hooks never ship. Each
+ * Every framework registers the strip the same way now — the esbuild plugin
+ * beside this file, which `bundle.js` composes for production builds — but the
+ * markers and the cut itself live here, once.
+ */
+
+const START_MARKER = '/* @dev-only:start */';
+const END_MARKER = '/* @dev-only:end */';
+
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const BLOCK_PATTERN = new RegExp(`${escapeRegex(START_MARKER)}[\\s\\S]*?${escapeRegex(END_MARKER)}`, 'g');
+
+/**
+ * Strip every dev-only block from a source string.
+ * @param {string} source
+ * @returns {string}
+ */
+function stripDevBlocks(source) {
+  // Fast path — most files carry no markers at all, and this runs over every
+  // module a bundle pulls in (dependencies included).
+  if (!source.includes(START_MARKER)) {
+    return source;
+  }
+
+  return source.replace(BLOCK_PATTERN, '');
+}
+
+module.exports = { stripDevBlocks, START_MARKER, END_MARKER };

package/dist/vendor/devkit/target-dependencies.js

@@ -0,0 +1,137 @@
+/**
+ * The dependency checks the retired `omega setup` carried
+ * ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)), split by what
+ * they need:
+ *
+ *   ensurePeerDependencies  the target cannot build without them — LOCAL half,
+ *                           each framework's ensure-target runs it on every verb
+ *   updateManager           asks the npm registry whether the framework itself
+ *                           is stale — NETWORK half, deploy-precheck runs it
+ *
+ * They share the same installer and the same version-check line, so they share
+ * a file rather than a copy each — and every framework shares THIS file rather
+ * than a drift-identical copy per package. What differs per framework is data,
+ * not logic: the peer-dep install-location map and the framework's own
+ * `safeInstall`, both passed in.
+ */
+
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const version = require('wonderful-version');
+const chalk = require('chalk').default;
+const { getLatestVersion } = require('./npm-registry.js');
+
+/**
+ * The consumer manifest at `projectDir`, its two dependency sections normalized.
+ *
+ * @param {string} projectDir - The target root.
+ * @returns {object} The manifest, with `dependencies`/`devDependencies` always objects.
+ */
+function readProject(projectDir) {
+  const project = jetpack.read(path.join(projectDir, 'package.json'), 'json') || {};
+  project.dependencies = project.dependencies || {};
+  project.devDependencies = project.devDependencies || {};
+  return project;
+}
+
+function logVersionCheck(log, name, installedVersion, latestVersion, isUpToDate) {
+  // A `file:` spec is the local-link era's answer — always current by definition.
+  if (installedVersion && installedVersion.startsWith('file:')) {
+    isUpToDate = true;
+  }
+
+  const installedLabel = installedVersion || '(none)';
+  const latestLabel = latestVersion || '(unknown)';
+  const status = isUpToDate ? chalk.green('Yes') : chalk.red('No');
+
+  log(`Checking if ${name} is up to date (${chalk.bold(installedLabel)} >= ${chalk.bold(latestLabel)}): ${status}`);
+}
+
+function install({ projectDir, project, log, safeInstall, pkg, ver, location }) {
+  ver = ver === 'latest' || !ver ? 'latest' : version.clean(ver);
+
+  const command = `npm install ${pkg}@${ver} ${location || '--save'}`;
+  log(`Installing: ${command}`);
+
+  return safeInstall(command)
+    .then(() => {
+      const projectUpdated = readProject(projectDir);
+      project.dependencies = projectUpdated.dependencies;
+      project.devDependencies = projectUpdated.devDependencies;
+      log(`Installed: ${pkg} ${ver}`);
+    });
+}
+
+/**
+ * Install any peer dependency the target is missing or behind on. A satisfied
+ * target installs nothing, which is what makes this safe on every verb.
+ *
+ * @param {object} input
+ * @param {string} input.projectDir - The target root.
+ * @param {object} input.package - The framework manifest (its peerDependencies).
+ * @param {function} input.log - Line logger.
+ * @param {Object<string, string>} [input.dependencyMap] - Per-dep install location (`'dev'` = --save-dev).
+ * @param {function} input.safeInstall - The framework's install runner.
+ */
+async function ensurePeerDependencies({ projectDir, package: frameworkPackage, log, dependencyMap, safeInstall }) {
+  const project = readProject(projectDir);
+  const requiredPeerDependencies = frameworkPackage.peerDependencies || {};
+  const map = dependencyMap || {};
+
+  for (const [dependency, rawVer] of Object.entries(requiredPeerDependencies)) {
+    const projectDependencyVersion = version.clean(project.dependencies[dependency] || project.devDependencies[dependency]);
+    const location = map[dependency] === 'dev' ? '--save-dev' : '';
+    const isUpToDate = version.is(projectDependencyVersion, '>=', rawVer);
+
+    const ver = version.clean(rawVer);
+
+    logVersionCheck(log, dependency, projectDependencyVersion, ver, isUpToDate);
+
+    if (!projectDependencyVersion || !isUpToDate) {
+      await install({ projectDir, project, log, safeInstall, pkg: dependency, ver, location });
+    }
+  }
+}
+
+/**
+ * Is the installed framework the latest published one? Hits the npm registry,
+ * so it rides `omega deploy`'s network precheck, never a build.
+ *
+ * @param {object} input
+ * @param {string} input.projectDir - The target root.
+ * @param {object} input.package - The framework manifest.
+ * @param {function} input.log - Line logger.
+ * @param {function} input.error - Error logger.
+ * @param {function} input.safeInstall - The framework's install runner.
+ */
+async function updateManager({ projectDir, package: frameworkPackage, log, error, safeInstall }) {
+  const project = readProject(projectDir);
+
+  // Either section counts (friction #12) — the framework is a build-time dep,
+  // but web/backend accept dependencies too; one rule everywhere.
+  const installedVersion = project.devDependencies[frameworkPackage.name] || project.dependencies[frameworkPackage.name];
+
+  if (!installedVersion) {
+    throw new Error(`No installed version of ${frameworkPackage.name} found in dependencies or devDependencies.`);
+  }
+
+  const latestVersion = (await getLatestVersion(frameworkPackage.name)) || '0.0.0';
+
+  const isUpToDate = version.is(installedVersion, '>=', latestVersion);
+  const levelDifference = version.levelDifference(installedVersion, latestVersion);
+
+  logVersionCheck(log, frameworkPackage.name, installedVersion, latestVersion, isUpToDate);
+
+  if (installedVersion.startsWith('file:')) {
+    return;
+  }
+
+  if (!isUpToDate) {
+    if (levelDifference === 'major' && installedVersion !== 'latest') {
+      return error(`Major version difference detected. Please update to ${latestVersion} manually.`);
+    }
+    await install({ projectDir, project, log, safeInstall, pkg: frameworkPackage.name, ver: latestVersion });
+  }
+}
+
+module.exports = { readProject, ensurePeerDependencies, updateManager, logVersionCheck };