@omega.js/backend 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/parse-audit.js

@@ -0,0 +1,74 @@
+/**
+ * Parse-audit: vm-parse every .js file under a tree WITHOUT executing it.
+ *
+ * Catches files that fail to PARSE in source corners no test ever loads —
+ * CLI commands, scaffold templates, setup machinery. The motivating incident
+ * (cp73c): a rename sweep corrupted regex literals in three backend
+ * setup-tests modules, leaving them SyntaxErrors for three checkpoints while
+ * every suite stayed green.
+ *
+ * CJS first (Module.wrap — the same wrapper node itself compiles modules
+ * with); files that fail the CJS parse are re-checked as ESM via node's own
+ * parser (`node --input-type=module --check`) so browser/ESM sources don't
+ * false-positive. Only files failing BOTH parses are reported.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const Module = require('node:module');
+const { execFileSync } = require('node:child_process');
+
+// Build output and dependency trees never gate a source audit
+const DEFAULT_SKIP = ['node_modules', 'dist', '.temp', '.cache', 'coverage', 'packaged', 'release'];
+
+/**
+ * Recursively parse-check every .js file under rootDir.
+ * @param {string} rootDir - Tree to audit (absolute or cwd-relative).
+ * @param {object} [options]
+ * @param {string[]} [options.skipDirs] - Directory NAMES to skip at any depth (replaces the default list).
+ * @returns {{ checked: number, failures: Array<{ file: string, error: string }> }}
+ *   `file` is relative to rootDir; `error` is the first line of the parse error.
+ */
+function parseAuditTree(rootDir, options = {}) {
+  const root = path.resolve(rootDir);
+  const skipDirs = new Set(options.skipDirs || DEFAULT_SKIP);
+
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name)) continue;
+        walk(path.join(dir, entry.name));
+      } else if (entry.name.endsWith('.js')) {
+        files.push(path.join(dir, entry.name));
+      }
+    }
+  };
+  walk(root);
+
+  const failures = [];
+  for (const file of files) {
+    const source = fs.readFileSync(file, 'utf8').replace(/^#!.*/, '');
+
+    try {
+      new vm.Script(Module.wrap(source), { filename: file });
+    } catch (cjsError) {
+      try {
+        execFileSync(process.execPath, ['--input-type=module', '--check'], {
+          input: source,
+          stdio: ['pipe', 'ignore', 'pipe'],
+        });
+      } catch (esmError) {
+        failures.push({
+          file: path.relative(root, file),
+          error: String(cjsError.message).split('\n')[0],
+        });
+      }
+    }
+  }
+
+  return { checked: files.length, failures };
+}
+
+module.exports = { parseAuditTree };

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/stop-signals.js

@@ -0,0 +1,28 @@
+/**
+ * "How is this run asked to stop?" The ONE list every supervisor registers.
+ *
+ * A supervisor is any process that owns a child, a watcher or a long-running
+ * loop it must unwind before it goes: the backend's emulator and test runner,
+ * the manager's `omega dev`, the web dev server, the log tails. Each of them
+ * used to hand-type its own subset, and the subsets disagreed. The manager
+ * registered SIGINT and SIGTERM only, so a CLOSED TERMINAL (SIGHUP) killed the
+ * orchestrator outright and its detached legs, the emulator tree among them,
+ * orphaned with their ports ([#629](https://github.com/Omega-JS-Stack/omega/issues/629)).
+ *
+ * A signal with no listener is not a shutdown: node kills THIS process only,
+ * and anything detached below it survives. So all three take the SAME teardown:
+ * Ctrl+C (SIGINT), a programmatic stop (a supervisor's own shutdown, `omega
+ * dev`'s stop, the journey lane, all SIGTERM), and a closed terminal (SIGHUP).
+ *
+ * Stdlib-only on purpose: a vendored module must not push a dependency onto
+ * its hosts.
+ */
+
+/**
+ * Every way a run is asked to stop.
+ *
+ * @type {string[]}
+ */
+const STOP_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+
+module.exports = { STOP_SIGNALS };

package/dist/vendor/devkit/test/assert.js

@@ -0,0 +1,120 @@
+// Tiny expect() — Jest/Vitest-compatible subset.
+// Each matcher throws on failure; the runner catches.
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== 'object') return false;
+
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((x, i) => deepEqual(x, b[i]));
+  }
+
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => deepEqual(a[k], b[k]));
+}
+
+function fmt(v) {
+  if (typeof v === 'string') return JSON.stringify(v);
+  if (v === undefined) return 'undefined';
+  try {
+    return JSON.stringify(v);
+  } catch (e) {
+    return String(v);
+  }
+}
+
+function fail(message) {
+  const err = new Error(message);
+  err.name = 'AssertionError';
+  throw err;
+}
+
+function buildMatchers(actual, negated) {
+  const not = negated ? 'not ' : '';
+
+  function check(cond, message) {
+    if (negated) cond = !cond;
+    if (!cond) fail(message);
+  }
+
+  return {
+    toBe(expected) {
+      check(actual === expected, `expected ${fmt(actual)} ${not}to be ${fmt(expected)}`);
+    },
+    toEqual(expected) {
+      check(deepEqual(actual, expected), `expected ${fmt(actual)} ${not}to deeply equal ${fmt(expected)}`);
+    },
+    toBeTruthy() {
+      check(!!actual, `expected ${fmt(actual)} ${not}to be truthy`);
+    },
+    toBeFalsy() {
+      check(!actual, `expected ${fmt(actual)} ${not}to be falsy`);
+    },
+    toBeDefined() {
+      check(actual !== undefined, `expected ${fmt(actual)} ${not}to be defined`);
+    },
+    toBeUndefined() {
+      check(actual === undefined, `expected ${fmt(actual)} ${not}to be undefined`);
+    },
+    toBeNull() {
+      check(actual === null, `expected ${fmt(actual)} ${not}to be null`);
+    },
+    toContain(item) {
+      const has = Array.isArray(actual)
+        ? actual.includes(item)
+        : (typeof actual === 'string' && actual.includes(item));
+      check(has, `expected ${fmt(actual)} ${not}to contain ${fmt(item)}`);
+    },
+    toHaveProperty(key) {
+      const has = actual != null && Object.prototype.hasOwnProperty.call(actual, key);
+      check(has, `expected ${fmt(actual)} ${not}to have property "${key}"`);
+    },
+    toMatch(regex) {
+      check(regex.test(actual), `expected ${fmt(actual)} ${not}to match ${regex}`);
+    },
+    toBeInstanceOf(cls) {
+      check(actual instanceof cls, `expected value ${not}to be instance of ${cls.name}`);
+    },
+    toBeGreaterThan(n) {
+      check(actual > n, `expected ${fmt(actual)} ${not}to be > ${n}`);
+    },
+    toBeLessThan(n) {
+      check(actual < n, `expected ${fmt(actual)} ${not}to be < ${n}`);
+    },
+    async toThrow(matcher) {
+      let threw = false;
+      let thrown;
+      try {
+        if (typeof actual === 'function') {
+          await actual();
+        }
+      } catch (e) {
+        threw = true;
+        thrown = e;
+      }
+      if (!threw) {
+        return check(false, `expected function ${not}to throw`);
+      }
+      if (matcher instanceof RegExp) {
+        check(matcher.test(thrown.message), `expected thrown message ${not}to match ${matcher} (got: ${thrown.message})`);
+      } else if (typeof matcher === 'string') {
+        check(thrown.message.includes(matcher), `expected thrown message ${not}to contain "${matcher}" (got: ${thrown.message})`);
+      } else {
+        check(true, '');
+      }
+    },
+  };
+}
+
+function expect(actual) {
+  const m = buildMatchers(actual, false);
+  m.not = buildMatchers(actual, true);
+  return m;
+}
+
+module.exports = expect;