@omega.js/backend 0.1.0

package/dist/cli/utils/ensure-target.js

@@ -0,0 +1,314 @@
+/**
+ * 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 and `ensureStaged()` calls this first,
+ * so build/dev/serve/emulator/test/deploy all heal the tree on the way past.
+ *
+ * What it guarantees, in this order (config first — the derived artifacts read
+ * it):
+ *
+ *   config/omega.json5      standalone targets only (inside a brand monorepo
+ *                           the brand root's `targets.backend` IS the config)
+ *   .firebaserc             derived from the resolved config's project id
+ *   firebase.json           scaffolded, or migrated onto the src/dist pillar
+ *   src/index.js            the AUTHORED Cloud Functions entry
+ *   firestore.rules         the brand's rules SOURCE half (the stage compiles it)
+ *   database.rules.json     the emulator dies ENOENT without it
+ *   package.json engines    the FRAMEWORK's pinned Cloud Functions runtime
+ *   package.json scripts    the standard verb scripts, rewritten to their
+ *                           defaults (#689 — the framework owns those keys)
+ *   src/defaults/**         the defaults tree (copy-if-missing; AGENTS.md and
+ *                           .gitignore live-sync their Default section)
+ *
+ * Everything here is copy-if-missing or merge-in-place — the one exception is
+ * the standard scripts above, which the framework owns outright in every
+ * target that isn't a custom server. A run that changes nothing writes nothing
+ * and says nothing. Anything that needs the network is NOT here — that belongs
+ * to the verb that needs it.
+ */
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const JSON5 = require('json5');
+const omegaConfig = require('../../vendor/config/index.js');
+
+const { assertScaffoldable } = require('../../vendor/devkit/scaffold-guard.js');
+
+const { scaffoldDefaults } = require('../../utils/scaffold-defaults.js');
+const { isCustomProject, frameworkOwnedScripts, FIREBASE_ONLY_SCAFFOLD } = require('./project-type');
+
+// The framework's own manifest — its `omega.functionsRuntime` is the pinned
+// Cloud Functions runtime every consumer app inherits (SSOT with the .nvmrc
+// lockstep in setup-tests/nvmrc-version.js). Deliberately decoupled from
+// `engines.node`, which is the honest DEV floor (`>=22`): the cloud runtime
+// is Firebase's to provide, the laptop only has to meet the floor.
+const frameworkPackage = require('../../../package.json');
+
+const TEMPLATES_DIR = path.resolve(__dirname, '../../../templates');
+
+/** Read a JSON5 file, `{}` when it is missing or empty. */
+function loadJSON(filePath) {
+  const contents = jetpack.read(filePath);
+  return contents ? JSON5.parse(contents) : {};
+}
+
+function hasContent(object) {
+  return Object.keys(object).length > 0;
+}
+
+/**
+ * The project id `.firebaserc` derives from.
+ *
+ * The config is the source of truth: a wizard-seeded brand carries
+ * cloud.config.projectId (the demo-<id> convention) before any artifact
+ * exists — .firebaserc derives from it, never the reverse.
+ *
+ * @param {string} projectDir - The target root.
+ * @returns {string} The project id.
+ */
+function resolveProjectId(projectDir) {
+  if (omegaConfig.hasOmegaConfig(projectDir) || omegaConfig.findBrandRoot(projectDir)) {
+    try {
+      const configured = omegaConfig.loadConfig(projectDir, 'backend').config.cloud?.config?.projectId;
+      if (configured) {
+        return configured;
+      }
+    } catch (e) {
+      // Unloadable config — the omega-config target check reports it
+    }
+  }
+
+  const saPath = path.join(projectDir, 'service-account.json');
+  if (jetpack.exists(saPath)) {
+    try {
+      const sa = JSON.parse(jetpack.read(saPath));
+      if (sa.project_id) {
+        return sa.project_id;
+      }
+    } catch (e) {
+      // Fall through
+    }
+  }
+
+  return process.env.GCLOUD_PROJECT || 'demo-project';
+}
+
+/**
+ * Scaffold the config artifacts a backend target cannot run without.
+ *
+ * @param {string} projectDir - The target root.
+ * @param {{ written: string[], changed: string[] }} result - Collector.
+ */
+function scaffoldConfigs(projectDir, result) {
+  // Custom mode has no Functions deploy and no emulator, so the Firebase-only
+  // artifacts below are scaffolded away entirely (#614). The list lives with
+  // the mode table, next to the verbs the same mode refuses.
+  const custom = isCustomProject(projectDir);
+  const skipsFirebaseFile = (file) => custom && FIREBASE_ONLY_SCAFFOLD.includes(file);
+
+  // Config FIRST (friction #11: config → derived artifacts, so .firebaserc
+  // below can read cloud.config.projectId). Inside a brand monorepo the target
+  // carries NO omega.json5 at all — brand `targets.*` is the per-target home
+  // (cp121c/cp122) and the stage step composes the runtime file. Standalone
+  // consumers (no brand root above) get the full template at the TARGET ROOT —
+  // the same escape hatch every other target uses.
+  if (!omegaConfig.hasOmegaConfig(projectDir) && !omegaConfig.findBrandRoot(projectDir)) {
+    jetpack.copy(path.join(TEMPLATES_DIR, 'config', 'omega.json5'), path.join(projectDir, 'config', 'omega.json5'));
+    result.written.push('config/omega.json5');
+  }
+
+  // .firebaserc — DERIVED from the resolved config (else service account / env)
+  if (!hasContent(loadJSON(path.join(projectDir, '.firebaserc')))) {
+    const projectId = resolveProjectId(projectDir);
+    jetpack.write(path.join(projectDir, '.firebaserc'), `${JSON.stringify({ projects: { default: projectId } }, null, 2)}\n`);
+    result.written.push('.firebaserc');
+  }
+
+  // firebase.json — scaffold or migrate
+  const firebaseJsonPath = path.join(projectDir, 'firebase.json');
+  const firebaseJSON = loadJSON(firebaseJsonPath);
+  if (skipsFirebaseFile('firebase.json')) {
+    // Nothing: not even the dist/ migration below, which would rewrite a
+    // file this mode never asked for.
+  } else if (!hasContent(firebaseJSON)) {
+    jetpack.copy(path.join(TEMPLATES_DIR, 'firebase.json'), firebaseJsonPath);
+    result.written.push('firebase.json');
+  } else {
+    // Migrate legacy `functions` → `dist` (src/dist pillar): the functions
+    // source and hosting public dir must point at the staged output tree.
+    let dirty = false;
+    const fnBlock = Array.isArray(firebaseJSON.functions) ? firebaseJSON.functions[0] : firebaseJSON.functions;
+    if (fnBlock && fnBlock.source === 'functions') {
+      fnBlock.source = 'dist';
+      dirty = true;
+    }
+    if (firebaseJSON.hosting && firebaseJSON.hosting.public === 'public') {
+      firebaseJSON.hosting.public = 'dist/public';
+      dirty = true;
+    }
+    if (dirty) {
+      jetpack.write(firebaseJsonPath, `${JSON.stringify(firebaseJSON, null, 2)}\n`);
+      result.changed.push('firebase.json (functions source + hosting public → dist/)');
+    }
+  }
+
+  // src/index.js — the AUTHORED Cloud Functions entry (src/dist pillar);
+  // the stage step mirrors it into dist/index.js
+  const indexPath = path.join(projectDir, 'src', 'index.js');
+  if (!jetpack.exists(indexPath)) {
+    jetpack.copy(path.join(TEMPLATES_DIR, 'index.js'), indexPath);
+    result.written.push('src/index.js');
+  }
+
+  // firestore.rules — the brand's SOURCE half (#255). Seeded HERE, before the
+  // stage compiles it, so a virgin target's first stage already has a real
+  // source to splice the framework half into. Migration off a legacy marker
+  // block + the hook lint belong to the firestore-rules-file check.
+  const firestoreRulesPath = path.join(projectDir, 'firestore.rules');
+  if (!skipsFirebaseFile('firestore.rules') && !jetpack.exists(firestoreRulesPath)) {
+    jetpack.copy(path.join(TEMPLATES_DIR, 'firestore.rules'), firestoreRulesPath);
+    result.written.push('firestore.rules');
+  }
+
+  // database.rules.json — firebase.json references it and the emulator dies
+  // ENOENT without it (friction #9). The template ships the v0.0.0-stamped
+  // marker block; the rules checks stamp the live version.
+  const databaseRulesPath = path.join(projectDir, 'database.rules.json');
+  if (!skipsFirebaseFile('database.rules.json') && !jetpack.exists(databaseRulesPath)) {
+    jetpack.copy(path.join(TEMPLATES_DIR, 'database.rules.json'), databaseRulesPath);
+    result.written.push('database.rules.json');
+  }
+}
+
+/**
+ * Sync the TARGET manifest — the engines pin and the standard verb scripts.
+ *
+ * engines.node: the stage step carries it into the derived dist/package.json
+ * (Cloud Functions runtime detection). Derived from the FRAMEWORK's pinned
+ * runtime, never the ambient node: a scaffold must produce the same app under
+ * any shell (cp195 journey catch — an ambient-24 run stamped 24 against the
+ * v22/* .nvmrc and boot died on the Manager.init version mismatch). A
+ * consumer-authored value is never overwritten.
+ *
+ * scripts: the opposite policy, and the same one the three sibling frameworks
+ * already run ([#689](https://github.com/Omega-JS-Stack/omega/issues/689)) —
+ * every key this framework declares is FRAMEWORK-owned and takes its default
+ * on every verb run, so an edited standard script heals instead of drifting
+ * (hook points are the customization seam). Keys the framework never declares
+ * are the consumer's own and are never touched; a custom-server backend keeps
+ * the ones its mode refuses (frameworkOwnedScripts is the one home of that).
+ *
+ * Identical content is not a write.
+ *
+ * @param {string} projectDir - The target root.
+ * @param {{ written: string[], changed: string[] }} result - Collector.
+ */
+function scaffoldPackageJson(projectDir, result) {
+  const manifestPath = path.join(projectDir, 'package.json');
+  const manifest = loadJSON(manifestPath);
+  const changes = [];
+
+  if (!(manifest.engines && manifest.engines.node)) {
+    const nodeVersion = String(parseInt(frameworkPackage.omega.functionsRuntime, 10));
+    manifest.engines = manifest.engines || {};
+    manifest.engines.node = nodeVersion;
+    changes.push(`engines.node = ${nodeVersion}`);
+  }
+
+  const owned = frameworkOwnedScripts(projectDir);
+  manifest.scripts = manifest.scripts || {};
+  for (const [key, command] of Object.entries(owned)) {
+    if (manifest.scripts[key] === command) continue;
+    manifest.scripts[key] = command;
+    changes.push(`scripts.${key}`);
+  }
+
+  if (changes.length === 0) return;
+
+  // npm's own shape, trailing newline included — the same byte contract the
+  // three sibling writers and the manager walk keep (jetpack.write emits none).
+  jetpack.write(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  result.changed.push(`package.json (${changes.join(', ')})`);
+}
+
+/**
+ * Apply the framework's defaults tree (src/defaults/**) to the target root via
+ * the shared devkit engine. The file map lives in src/utils/scaffold-defaults.js:
+ * copy-if-missing for everything, marker-section merge (Default =
+ * framework-owned, Custom = consumer-owned) for AGENTS.md and .gitignore.
+ *
+ * @param {string} projectDir - The target root.
+ * @param {{ written: string[], merged: string[] }} result - Collector.
+ */
+function copyDefaults(projectDir, result) {
+  const defaultsDir = path.resolve(__dirname, '../../defaults');
+
+  // Optional — older @omega.js/backend versions shipped no defaults tree
+  if (!jetpack.exists(defaultsDir)) return;
+
+  const applied = scaffoldDefaults({
+    outputDir: projectDir,
+    logger: { log: () => {}, warn: () => {}, error: () => {} },
+  });
+
+  result.written.push(...applied.written);
+  result.merged.push(...applied.merged);
+}
+
+/**
+ * Sweep the transient artifacts older runs left in the tree — today just the
+ * reload trigger `npx omega watch` writes. Log sweeping belongs to the boot
+ * lanes (base-command's sweepStaleLogs), which run it per boot.
+ *
+ * @param {string} projectDir - The target root.
+ */
+function cleanupGeneratedArtifacts(projectDir) {
+  const triggerFile = path.join(projectDir, 'functions', 'omega-reload-trigger.js');
+  if (jetpack.exists(triggerFile)) {
+    jetpack.remove(triggerFile);
+  }
+}
+
+/**
+ * Make the target whole — idempotent, offline, and quiet when there is
+ * nothing to do.
+ *
+ * @param {object} options
+ * @param {string} options.projectDir - The target root.
+ * @param {function} [options.log] - Line logger (silent by default).
+ * @returns {{ written: string[], merged: string[], changed: string[] }}
+ *   Target-relative paths per outcome — empty on a no-op run.
+ */
+function ensureTarget(options) {
+  const projectDir = options.projectDir;
+  const log = options.log || (() => {});
+  const result = { written: [], merged: [], changed: [] };
+
+  // The framework's own tree is not a consumer target. Running the framework's
+  // suite from packages/backend puts the framework at the cwd, and a verb that
+  // scaffolds unconditionally would scatter the consumer defaults through the
+  // package. Refuse, quietly: this is a normal state, not a broken one.
+  // (Sibling of the same guard in @omega.js/desktop's ensure-target.)
+  if (loadJSON(path.join(projectDir, 'package.json')).name === frameworkPackage.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);
+
+  scaffoldConfigs(projectDir, result);
+  scaffoldPackageJson(projectDir, result);
+  copyDefaults(projectDir, result);
+  cleanupGeneratedArtifacts(projectDir);
+
+  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, resolveProjectId };

package/dist/cli/utils/project-type.js

@@ -0,0 +1,140 @@
+/**
+ * Which SHAPE this backend target runs and deploys as
+ * ([#584](https://github.com/Omega-JS-Stack/omega/issues/584)):
+ * `firebase` — Cloud Functions, the default and what most brands are — or
+ * `custom` — the same Express app listening on `PORT`, deployed to a
+ * container host (Render & co). The switch is the brand's own config,
+ * `targets.backend.projectType`, so ONE file decides it for the runtime
+ * (`Manager.init`) and for the CLI alike.
+ *
+ * Custom mode takes three VERBS away, and FIREBASE_ONLY_VERBS is the one home
+ * of that list: the Functions deploy, the local emulator, and the emulator test
+ * run. It also takes away the Firebase-only ARTIFACTS those verbs read —
+ * FIREBASE_ONLY_SCAFFOLD and FIREBASE_ONLY_SETUP_CHECKS are the one home of
+ * that list ([#614](https://github.com/Omega-JS-Stack/omega/issues/614)) — and
+ * the package SCRIPTS that run them, which the framework manifest's
+ * `projectScriptsCustomOwned` names
+ * ([#689](https://github.com/Omega-JS-Stack/omega/issues/689)).
+ * Everything else — the routes, the schemas, the auth middleware, every
+ * helper, and the rest of setup — is identical in both modes, which is the
+ * whole point of the mode.
+ */
+const chalk = require('chalk').default;
+
+const { hasOmegaConfig, loadConfig, backendProjectType } = require('../../vendor/config/index.js');
+
+// The framework's own manifest: `projectScripts` (every standard target script)
+// and `projectScriptsCustomOwned` (the ones a custom-server backend owns
+// instead). Declared THERE, not here, because the manager walk reads the same
+// pair off the installed package without loading any backend code (#689).
+const frameworkPackage = require('../../../package.json');
+
+// verb → what replaces it in custom mode. A refusal that doesn't name the
+// lane is just a wall.
+const FIREBASE_ONLY_VERBS = {
+  deploy: "a custom backend publishes through its host (Render & co) — put that command in this target's `deploy` script, which the brand-root `omega deploy` runs",
+  serve: 'a custom backend runs its own server — `npm start` boots it on PORT',
+  emulator: 'there are no Cloud Functions to emulate — `npm start` boots the server on PORT',
+  test: "the emulator lane needs Cloud Functions — `npm test` runs this target's static suite",
+};
+
+// The files the scaffold writes ONLY for the Firebase lane: firebase.json
+// (deploy targets + emulator config), and the rules sources firebase.json
+// points at. A custom backend deploys through its host and has no emulator, so
+// scaffolding these leaves a consumer files to delete
+// ([#614](https://github.com/Omega-JS-Stack/omega/issues/614)). Skipped, never
+// removed: an existing custom project keeps whatever it authored.
+const FIREBASE_ONLY_SCAFFOLD = ['firebase.json', 'firestore.rules', 'database.rules.json'];
+
+// The setup CHECKS that exist only for those artifacts — every check that
+// reads or writes firebase.json, plus the ones that seed the rules and index
+// files. Module names under src/cli/commands/setup-tests/, which is where the
+// registry resolves them.
+const FIREBASE_ONLY_SETUP_CHECKS = [
+  'is-firebase-project',
+  'firestore-rules-in-json',
+  'firestore-indexes-in-json',
+  'realtime-rules-in-json',
+  'storage-rules-in-json',
+  'remoteconfig-template-in-json',
+  'emulator-config',
+  'hosting-rewrites',
+  'hosting-folder',
+  'firestore-rules-file',
+  'firestore-indexes-file',
+  'firestore-indexes-required',
+  'firestore-indexes-synced',
+  'realtime-rules-file',
+  'storage-rules-file',
+];
+
+/**
+ * The project type of the backend target at `targetRoot`.
+ *
+ * A missing, unreadable or unparseable config reads 'firebase': that is the
+ * default, so it changes nothing, and the config problem itself belongs to the
+ * lane that loads it properly (the target checks), not to a shape question.
+ *
+ * @param {string} targetRoot - The backend target root.
+ * @returns {'firebase'|'custom'}
+ */
+function resolveProjectType(targetRoot) {
+  try {
+    if (!hasOmegaConfig(targetRoot)) return 'firebase';
+    return backendProjectType(loadConfig(targetRoot, 'backend').config);
+  } catch {
+    return 'firebase';
+  }
+}
+
+/**
+ * @param {string} targetRoot - The backend target root.
+ * @returns {boolean} True when this backend runs as a custom server.
+ */
+function isCustomProject(targetRoot) {
+  return resolveProjectType(targetRoot) === 'custom';
+}
+
+/**
+ * The package scripts THIS framework owns for the target at `targetRoot` — the
+ * ONE home of the ownership semantics, read by both writers: the scaffold every
+ * verb runs (ensure-target.js) and the setup check that holds a target to them
+ * (setup-tests/npm-project-scripts.js).
+ *
+ * Every `projectScripts` key in firebase mode. In custom mode, all but the keys
+ * whose verbs that mode refuses — those are the BRAND's (its own server command,
+ * its own host deploy), so they are never written and never scaffolded.
+ *
+ * @param {string} targetRoot - The backend target root.
+ * @returns {Object} Script key → the command this framework owns it as.
+ */
+function frameworkOwnedScripts(targetRoot) {
+  const declared = frameworkPackage.projectScripts || {};
+  if (!isCustomProject(targetRoot)) return { ...declared };
+
+  const brandOwned = frameworkPackage.projectScriptsCustomOwned || [];
+  return Object.fromEntries(Object.entries(declared).filter(([key]) => !brandOwned.includes(key)));
+}
+
+/**
+ * The gate every Firebase-only verb opens with. When this target runs in
+ * custom mode it prints the refusal — the mode, and the lane that replaces
+ * this verb — fails the process, and returns true; the caller returns at once.
+ *
+ * The exit code matters: these verbs are chained in package scripts and fanned
+ * out by the manager, and a refusal that read green would look like a deploy
+ * that happened.
+ *
+ * @param {string} targetRoot - The backend target root.
+ * @param {keyof FIREBASE_ONLY_VERBS} verb - The verb being refused.
+ * @returns {boolean} True when the caller must stop.
+ */
+function refuseWhenCustom(targetRoot, verb) {
+  if (!isCustomProject(targetRoot)) return false;
+
+  console.log(chalk.yellow(`\n⊘ omega ${verb}: this backend runs \`projectType: 'custom'\` (config/omega.json5 → targets.backend) — ${FIREBASE_ONLY_VERBS[verb]}.`));
+  process.exitCode = 1;
+  return true;
+}
+
+module.exports = { resolveProjectType, isCustomProject, refuseWhenCustom, frameworkOwnedScripts, FIREBASE_ONLY_VERBS, FIREBASE_ONLY_SCAFFOLD, FIREBASE_ONLY_SETUP_CHECKS };

package/dist/cli/utils/public-files.js

@@ -0,0 +1,49 @@
+// Hosting boilerplate generator — public/index.html + public/404.html from
+// templates/public/. Consumers never edit or track these files (setup
+// overwrites them on every run; the Default Values .gitignore ignores
+// /public/), so they behave like the root package.json proxy:
+// framework-generated output.
+//
+// Two entry points:
+//   - writePublicFiles (setup test, overwrite: true) — authoritative regen
+//     with the brand URL from the consumer's config/omega.json5
+//   - ensurePublicFiles (emulator boot / deploy, fill-if-missing) — a fresh
+//     clone has no public/ at all (it's gitignored), and firebase-tools
+//     refuses to boot or deploy hosting without the folder; this fills it
+//     without requiring a setup run first
+
+const jetpack = require('fs-jetpack');
+const path = require('path');
+const powertools = require('node-powertools');
+const { hasOmegaConfig, loadConfig } = require('../../vendor/config/index.js');
+
+const TEMPLATE_DIR = path.resolve(__dirname, '../../../templates/public');
+const FILES = ['index.html', '404.html'];
+
+function writePublicFiles(projectPath, options) {
+  options = options || {};
+
+  FILES.forEach((file) => {
+    const destination = path.join(projectPath, 'public', file);
+
+    if (!options.overwrite && jetpack.exists(destination)) {
+      return;
+    }
+
+    const template = jetpack.read(path.join(TEMPLATE_DIR, file));
+    jetpack.write(destination, powertools.template(template, { url: options.url || '' }));
+  });
+}
+
+function ensurePublicFiles(projectPath) {
+  let url = '';
+  try {
+    url = hasOmegaConfig(projectPath) ? (loadConfig(projectPath, 'backend').config.brand?.url || '') : '';
+  } catch (e) {
+    // Unreadable config — boilerplate links home to '' until setup writes the real one
+  }
+
+  writePublicFiles(projectPath, { url, overwrite: false });
+}
+
+module.exports = { writePublicFiles, ensurePublicFiles };

package/dist/cli/utils/safe-install.js

@@ -0,0 +1,4 @@
+// Shared devkit module — vendored into dist/vendor/devkit at prepare time by the
+// preparePackage `after` hook. This shim keeps the framework's internal require
+// paths stable while the implementation lives in @omega.js/devkit.
+module.exports = require('../../vendor/devkit/safe-install.js');

package/dist/cli/utils/spawn-shell.js

@@ -0,0 +1,94 @@
+/**
+ * Starting a child on a host whose shell you do not know.
+ *
+ * Two shapes, because the CLI has two kinds of child, and ONE rule underneath
+ * both: the binary is never named by an absolute path we resolved ourselves —
+ * the host's own resolver finds it.
+ *
+ *   spawnShell(command)        a command LINE the caller composed
+ *                              (`firebase emulators:start --only …`)
+ *   spawnOnPath(name, args)    a bare command NAME plus an argv
+ *                              (`nodemon`, ['--watch', dir])
+ *
+ * The platform-specific part is the shell, and it is what this module owns:
+ *   - Unix: `sh -c <command>` for a line; a bare name spawns directly, since
+ *     execvp already searches PATH and skipping the shell keeps the returned
+ *     child the REAL process (callers pipe its stdout and kill it by pid).
+ *   - Windows: `cmd.exe /c …` for both. There is no `sh`, and an npm-installed
+ *     bin is a `.cmd` shim that Node's CreateProcess cannot execute directly —
+ *     only a shell can, and only the shell applies PATHEXT to a bare name.
+ *
+ * Explicit `cmd.exe /c` rather than `shell: true`: an ARRAY of args under
+ * `shell: true` trips Node 24's DEP0190 deprecation warning, and the explicit
+ * form is the supported warning-free path. Node quotes each argv entry it hands
+ * to CreateProcess, so a path with spaces survives with nothing to escape here.
+ * Same call shape as `@omega.js/desktop`'s `omega runner`, which hit the trap
+ * first (`packages/desktop/src/commands/runner.js` ~313).
+ */
+// The module OBJECT, never a destructured `spawn`: the binding is read at CALL
+// time, so `child_process.spawn` stays a live seam a test can stand in for
+// ([#769](https://github.com/Omega-JS-Stack/omega/issues/769)). Destructuring
+// here would freeze whatever `spawn` was at this module's first require —
+// which, for a module every CLI command loads, is before any test can reach it.
+const childProcess = require('child_process');
+
+/**
+ * What actually runs, for a composed command LINE. Pure — the test seam.
+ *
+ * @param {string} command - The command line
+ * @param {string} [platform] - Host platform
+ * @returns {[string, string[]]} [binary, args]
+ */
+function shellInvocation(command, platform = process.platform) {
+  return platform === 'win32'
+    ? ['cmd.exe', ['/c', command]]
+    : ['sh', ['-c', command]];
+}
+
+/**
+ * What actually runs, for a bare command NAME plus an argv. Pure — the test seam.
+ *
+ * @param {string} name - Bare command name, never a resolved path
+ * @param {string[]} [args] - Its arguments, unquoted
+ * @param {string} [platform] - Host platform
+ * @returns {[string, string[]]} [binary, args]
+ */
+function pathInvocation(name, args = [], platform = process.platform) {
+  return platform === 'win32'
+    ? ['cmd.exe', ['/c', name, ...args]]
+    : [name, args];
+}
+
+/**
+ * Spawn a composed command LINE through the host's shell.
+ *
+ * @param {string} command - The command line to run
+ * @param {object} [options] - Passed to child_process.spawn verbatim
+ * @returns {import('child_process').ChildProcess}
+ */
+function spawnShell(command, options = {}) {
+  const [bin, args] = shellInvocation(command);
+
+  return childProcess.spawn(bin, args, options);
+}
+
+/**
+ * Spawn a command by BARE NAME, letting the host resolve it off PATH.
+ *
+ * This is the counterpart to `commandOnPath()`: that probe answers whether a
+ * tool is installed, and this runs it. The probe's answer is never what gets
+ * spawned — on Windows `where` prints the extensionless shell shim first, and
+ * neither that shim nor the `.cmd` beside it is executable by CreateProcess.
+ *
+ * @param {string} name - Bare command name, e.g. 'nodemon'
+ * @param {string[]} [args] - Its arguments
+ * @param {object} [options] - Passed to child_process.spawn verbatim
+ * @returns {import('child_process').ChildProcess}
+ */
+function spawnOnPath(name, args = [], options = {}) {
+  const [bin, spawnArgs] = pathInvocation(name, args);
+
+  return childProcess.spawn(bin, spawnArgs, options);
+}
+
+module.exports = { spawnShell, spawnOnPath, shellInvocation, pathInvocation };