@omega.js/desktop 0.50.0 → 0.52.0

package/dist/vendor/devkit/pack-local.js

@@ -0,0 +1,388 @@
+/**
+ * pack-local: make a tree's `file:` dependencies installable somewhere else
+ * ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)).
+ *
+ * A remote install can only resolve what travels with it: a dependency spelled
+ * `file:../../../../packages/web` resolves to nothing on a runner or inside
+ * Cloud Build, and an install that runs `npm ci` also demands a
+ * package-lock.json matching the uploaded shape.
+ *
+ * This stages an INSTALL ROOT in place: packs each LOCAL package the install
+ * needs into `<dir>/omega_modules/*.tgz` (npm pack runs the package's own
+ * prepare, so the tarball always reflects current source), respells every
+ * manifest that names one, and regenerates the lockfile against that shape.
+ * `restore()` puts each touched manifest and the lockfile back verbatim and
+ * removes the tarball folder, and a FAILING stage restores before it throws,
+ * so a stopped deploy never leaves a half-staged tree.
+ *
+ * `dir` is any install root: a brand root with workspaces, a standalone target,
+ * or a backend's generated functions folder. What gets packed is three things,
+ * not one:
+ *
+ *   1. the outside-the-dir `file:` deps of `<dir>/package.json` AND of every
+ *      workspace member manifest (npm resolves the whole workspace on any
+ *      install, so one linked member breaks the install of a clean one). Each
+ *      manifest's spec is respelled relative to ITSELF.
+ *   2. transitively, each packed package's own @omega.js runtime deps that
+ *      resolve through a node_modules SYMLINK. @omega.js/client is a real
+ *      runtime dependency of @omega.js/backend, never vendored and unpublished
+ *      under the publish latch, so packing only the framework left the lock
+ *      regen asking the registry for it (404, no deploy, #331). Those are
+ *      redirected by an `overrides` entry on the ROOT manifest, npm honoring
+ *      overrides at the install root only.
+ *   3. the overrides the ENCLOSING workspace root carries, when `dir` is itself
+ *      inside a staged tree. A member installed on its own is its own install
+ *      root, so an override it inherited has to travel with it.
+ *
+ * A spec that already points at a `.tgz` is COPIED, never packed again: that is
+ * the SECOND HOP, where the runner stages a target out of the snapshot it was
+ * handed and the sources are a machine away. It is also what makes the module
+ * idempotent, a staged dir spelling every local dep inside itself and therefore
+ * collecting nothing on a re-stage.
+ */
+
+// Libraries
+const fs = require('fs');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const powertools = require('node-powertools');
+const chalk = require('chalk').default;
+const { regenerateLockfile } = require('./lockfile.js');
+
+// Constants
+const STAGING_DIR = 'omega_modules';
+const SCOPE = '@omega.js/';
+const FILE_SPEC = 'file:';
+const DEP_BLOCKS = ['dependencies', 'devDependencies'];
+
+/**
+ * Is `target` inside `dir` (or the dir itself)?
+ * @param {string} dir - The install root.
+ * @param {string} target - An absolute path.
+ * @returns {boolean} True when the install already carries it.
+ */
+function isInside(dir, target) {
+  return target === dir || (target + path.sep).startsWith(dir + path.sep);
+}
+
+/** A `file:` spec for a path, always POSIX-spelled (npm reads no backslashes). */
+function fileSpec(from, target) {
+  return FILE_SPEC + path.relative(from, target).split(path.sep).join('/');
+}
+
+/**
+ * Resolve a LINKED local package: the first node_modules entry walking up from
+ * `fromDir` (mirroring Node resolution, since npm workspaces and `omega i local`
+ * hoist to the brand/monorepo root), and only when that entry is a SYMLINK. A
+ * symlink IS the local-era shape, and the registry may have no copy of what it
+ * points at; a real directory is a registry install the remote can fetch itself.
+ * @param {string} name - Package name.
+ * @param {string} fromDir - Directory whose manifest declares it.
+ * @returns {string|null} Absolute real path of the linked checkout, or null.
+ */
+function resolveLinkedPackage(name, fromDir) {
+  let current = path.resolve(fromDir);
+
+  while (true) {
+    const candidate = path.join(current, 'node_modules', name);
+    const entry = jetpack.inspect(candidate);
+
+    if (entry) {
+      if (entry.type !== 'symlink') {
+        return null;
+      }
+      const real = fs.realpathSync(candidate);
+      return jetpack.exists(path.join(real, 'package.json')) ? real : null;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+/** The workspace globs a manifest declares, in either supported spelling. */
+function workspaceGlobs(pkg) {
+  const workspaces = (pkg || {}).workspaces;
+  if (!workspaces) {
+    return [];
+  }
+
+  return Array.isArray(workspaces) ? workspaces : (workspaces.packages || []);
+}
+
+/**
+ * Every manifest an install of `dir` resolves: the root's, then each workspace
+ * member's.
+ * @param {string} dir - The install root.
+ * @param {object} pkg - Its parsed package.json.
+ * @returns {Array<{ dir: string, file: string, pkg: object, root: boolean }>} The manifests.
+ */
+function collectManifests(dir, pkg) {
+  const manifests = [{ dir, file: path.join(dir, 'package.json'), pkg, root: true }];
+
+  for (const pattern of workspaceGlobs(pkg)) {
+    for (const match of jetpack.find(dir, { matching: `${pattern}/package.json`, files: true }) || []) {
+      const file = path.resolve(match);
+      // An install never reads a manifest out of node_modules as a member
+      if (file.split(path.sep).includes('node_modules')) {
+        continue;
+      }
+
+      const member = jetpack.read(file, 'json');
+      if (member) {
+        manifests.push({ dir: path.dirname(file), file, pkg: member, root: false });
+      }
+    }
+  }
+
+  return manifests;
+}
+
+/**
+ * The nearest ancestor manifest declaring workspaces: the install root `dir`
+ * belonged to before it became one of its own, and therefore the home of the
+ * overrides it inherits.
+ * @param {string} dir - The install root being staged.
+ * @returns {{ dir: string, pkg: object }|null} The enclosing workspace root.
+ */
+function enclosingWorkspaceRoot(dir) {
+  let current = path.dirname(path.resolve(dir));
+
+  while (true) {
+    const pkg = jetpack.read(path.join(current, 'package.json'), 'json');
+    if (pkg && workspaceGlobs(pkg).length) {
+      return { dir: current, pkg };
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+/**
+ * Every local package the install must carry, and where each one is named.
+ *
+ * Two shapes ride together: an ENTRY is one place a manifest names a package
+ * (respelled in place, or redirected by an override on the root), and a SOURCE
+ * is the package itself (packed or copied exactly once, however many entries
+ * name it).
+ *
+ * @param {object} options - Options.
+ * @param {string} options.dir - The install root being staged.
+ * @param {Array<object>} options.manifests - collectManifests() output.
+ * @returns {{ entries: Array<object>, sources: Array<{ name: string, from: string }> }}
+ *   Sources in pack order: direct first, then the linked ones they pull in.
+ */
+function collectTargets({ dir, manifests }) {
+  const entries = [];
+  const sources = [];
+  const claimed = new Set();
+  const rootManifest = manifests[0];
+
+  const add = (entry) => {
+    entries.push(entry);
+    if (!claimed.has(entry.name)) {
+      claimed.add(entry.name);
+      sources.push({ name: entry.name, from: entry.from });
+    }
+  };
+
+  // Direct: file: specs resolving OUTSIDE the dir, per manifest. A spec already
+  // pointing inside is what the install carries, so it stays as it is.
+  for (const manifest of manifests) {
+    for (const block of DEP_BLOCKS) {
+      for (const [name, spec] of Object.entries(manifest.pkg[block] || {})) {
+        if (!spec.startsWith(FILE_SPEC)) {
+          continue;
+        }
+
+        const from = path.resolve(manifest.dir, spec.slice(FILE_SPEC.length));
+        if (!isInside(dir, from)) {
+          add({ name, from, manifest, block });
+        }
+      }
+    }
+  }
+
+  // Inherited: the overrides of the workspace root this dir is a member of, the
+  // ones npm would have applied to it there (the second hop's linked client).
+  const enclosing = enclosingWorkspaceRoot(dir);
+  const inherited = enclosing ? enclosing.pkg.overrides || {} : {};
+  const ownOverrides = rootManifest.pkg.overrides || {};
+
+  for (const [name, spec] of Object.entries({ ...inherited, ...ownOverrides })) {
+    if (typeof spec !== 'string' || !spec.startsWith(FILE_SPEC) || claimed.has(name)) {
+      continue;
+    }
+
+    const base = ownOverrides[name] === spec ? rootManifest.dir : enclosing.dir;
+    const from = path.resolve(base, spec.slice(FILE_SPEC.length));
+    if (!isInside(dir, from)) {
+      add({ name, from, manifest: rootManifest, block: null });
+    }
+  }
+
+  // Transitive: each packed package's linked @omega.js runtime deps. A copied
+  // tarball has none to walk: whatever it needed was resolved a hop ago and
+  // rides along as an inherited override.
+  for (let index = 0; index < sources.length; index++) {
+    const source = sources[index];
+    if (source.from.endsWith('.tgz')) {
+      continue;
+    }
+
+    const manifest = jetpack.read(path.join(source.from, 'package.json'), 'json');
+    for (const name of Object.keys((manifest || {}).dependencies || {})) {
+      if (!name.startsWith(SCOPE) || claimed.has(name)) {
+        continue;
+      }
+
+      const from = resolveLinkedPackage(name, source.from);
+      if (!from) {
+        continue; // Registry-installed (or absent): npm resolves it the normal way
+      }
+
+      add({ name, from, manifest: rootManifest, block: null });
+    }
+  }
+
+  return { entries, sources };
+}
+
+/**
+ * Stage an install root's local packages into it.
+ *
+ * @param {object} options - Options.
+ * @param {string} options.dir - The install root: a brand root, a target, or a
+ *   generated functions folder.
+ * @param {Function} [options.log] - One line per step (silent by default).
+ * @returns {Promise<{ staged: string[], restore: Function }>} The packed names,
+ *   and the restore that puts the tree back exactly as it was found.
+ */
+async function stageLocalPackages({ dir, log = () => {} }) {
+  const root = path.resolve(dir);
+  const lockPath = path.join(root, 'package-lock.json');
+  const stagingPath = path.join(root, STAGING_DIR);
+
+  const pkg = jetpack.read(path.join(root, 'package.json'), 'json');
+  if (!pkg) {
+    return { staged: [], restore: async () => {} };
+  }
+
+  const manifests = collectManifests(root, pkg);
+  const rootManifest = manifests[0];
+  const { entries, sources } = collectTargets({ dir: root, manifests });
+
+  if (!sources.length) {
+    return { staged: [], restore: async () => {} };
+  }
+
+  // Originals, restored verbatim after the deploy and after a failure
+  const touched = [...new Set(entries.map((entry) => entry.manifest))];
+  const originals = touched.map((manifest) => ({ file: manifest.file, contents: jetpack.read(manifest.file) }));
+  const originalLock = jetpack.read(lockPath);
+
+  const restore = async () => {
+    for (const original of originals) {
+      jetpack.write(original.file, original.contents);
+    }
+
+    if (originalLock === undefined) {
+      jetpack.remove(lockPath);
+    } else {
+      jetpack.write(lockPath, originalLock);
+    }
+
+    jetpack.remove(stagingPath);
+  };
+
+  try {
+    jetpack.remove(stagingPath);
+    jetpack.dir(stagingPath);
+
+    const tarballs = {};
+
+    for (const source of sources) {
+      // A `.tgz` was packed a hop ago, by the stage that produced the tree this
+      // one is staging out of: copying it keeps the artifact identical and asks
+      // nothing of sources that are a machine away.
+      if (source.from.endsWith('.tgz')) {
+        if (!jetpack.exists(source.from)) {
+          throw new Error(`Local dependency ${source.name} names a tarball that is not there: ${source.from}`);
+        }
+
+        const filename = path.basename(source.from);
+        jetpack.copy(source.from, path.join(stagingPath, filename));
+        tarballs[source.name] = filename;
+        log(`  ${chalk.green('✓')} Copied ${chalk.cyan(source.name)} → ${STAGING_DIR}/${filename}`);
+        continue;
+      }
+
+      if (!jetpack.exists(path.join(source.from, 'package.json'))) {
+        throw new Error(`Local dependency ${source.name} has no package.json at ${source.from}`);
+      }
+
+      log(`  ${chalk.dim('→')} Packing local package ${chalk.cyan(source.name)}...`);
+
+      const output = await powertools.execute(
+        `npm pack --pack-destination "${stagingPath}" --foreground-scripts=false`,
+        { log: false, config: { cwd: source.from } },
+      );
+
+      const filename = String(output).trim().split('\n').pop().trim();
+      if (!filename.endsWith('.tgz') || !jetpack.exists(path.join(stagingPath, filename))) {
+        throw new Error(`npm pack for ${source.name} did not produce a tarball (got: ${filename || 'nothing'})`);
+      }
+
+      tarballs[source.name] = filename;
+      log(`  ${chalk.green('✓')} Staged ${chalk.cyan(source.name)} → ${STAGING_DIR}/${filename}`);
+    }
+
+    const overrides = {};
+
+    for (const entry of entries) {
+      const tarball = path.join(stagingPath, tarballs[entry.name]);
+
+      if (entry.block) {
+        // Relative to the manifest that names it: a member's spec climbs out of
+        // its own folder, the root's does not.
+        entry.manifest.pkg[entry.block][entry.name] = fileSpec(entry.manifest.dir, tarball);
+      } else {
+        // A packed package still declares its own REGISTRY spec internally
+        // (`@omega.js/client: ^0.1.0`), so only an override redirects that
+        // nested resolution to the artifact beside it.
+        overrides[entry.name] = fileSpec(root, tarball);
+      }
+    }
+
+    if (Object.keys(overrides).length > 0) {
+      rootManifest.pkg.overrides = Object.assign({}, rootManifest.pkg.overrides, overrides);
+    }
+
+    for (const manifest of touched) {
+      jetpack.write(manifest.file, `${JSON.stringify(manifest.pkg, null, 2)}\n`);
+    }
+
+    // A remote install runs `npm ci`, so the uploaded lockfile must match the
+    // staged shape, regenerated from scratch (the one helper keeps it THIS
+    // dir's lock, never an enclosing workspace root's).
+    log(`  ${chalk.dim('→')} Regenerating package-lock.json for the staged shape...`);
+    jetpack.remove(lockPath);
+    await regenerateLockfile({ root });
+  } catch (error) {
+    // Loud and clean: the deploy stops here, and the tree goes back exactly as
+    // it was rather than sitting half-staged.
+    await restore();
+    throw new Error(`Local-package staging failed, nothing deployed and ${path.basename(root)}/ restored:\n${error.message}`);
+  }
+
+  return { staged: sources.map((source) => source.name), restore };
+}
+
+module.exports = { stageLocalPackages, STAGING_DIR };

package/dist/vendor/devkit/preludes/index.js

@@ -0,0 +1,120 @@
+/**
+ * runPreludes: the BOOT PRELUDE list every verb passes through
+ * ([#890](https://github.com/Omega-JS-Stack/omega/issues/890)).
+ *
+ * One seam already sits above every verb on all five CLIs: the `freshnessBoot`
+ * call that heals a stale locally-linked dist before anything runs. Anything
+ * else the whole CLI surface must settle first had nowhere to live, so it lived
+ * nowhere: a brand clone pointing at a redirected GitHub repo was checked by no
+ * verb at all. This is that place: the preludes run right after the freshness
+ * boot, in list order, before the verb.
+ *
+ * Each prelude is ONE file with one concern, exporting `{ name, verbs, run }`,
+ * and declares what it targets: `'all'`, one verb name, or a list of them. The
+ * runner filters by the verb about to run, as TYPED, before a framework's
+ * alias table resolves it, since the tables are the frameworks' and this runs
+ * above them, so an `'all'` prelude is the one that covers `-v` and a bare
+ * `omega` too.
+ *
+ * A prelude is CHEAP and NON-INTERACTIVE: local reads, at most one network
+ * call, never a prompt. Anything heavier is a manage op in its own service,
+ * where a walk reports it. A prelude that stops the run THROWS with one line of
+ * why, which this runner prints before exiting 1, the same presentation the
+ * freshness boot's loud stops use, so a refused boot reads the same whichever
+ * step refused it.
+ *
+ * Nothing here caches per process: a dispatcher hop that re-enters a `run()`
+ * runs the preludes again, and every prelude being idempotent, the second pass
+ * is a local read that finds its work already done.
+ */
+
+// The list. Order is the boot order.
+const PRELUDES = [
+  require('./origin-heal.js'),
+];
+
+/**
+ * The verb a prelude list filters on: the first positional of the invocation.
+ * A flag there (`--version`) is no verb: the CLI is about to run its default
+ * command, which only an `'all'` prelude covers.
+ *
+ * @param {string} [verb] - The raw first argument.
+ * @returns {string|null} The verb, or null when the invocation names none.
+ */
+function normalizeVerb(verb) {
+  return typeof verb === 'string' && verb.length > 0 && !verb.startsWith('-') ? verb : null;
+}
+
+/**
+ * Does this prelude target the verb about to run?
+ *
+ * @param {{ name: string, verbs: string|string[] }} prelude - The prelude.
+ * @param {string|null} verb - The normalized verb.
+ * @returns {boolean}
+ * @throws {Error} When the prelude declares no usable `verbs`. A list entry
+ *   nobody can target is a programmer error, and a silent skip would make it
+ *   look like a prelude that simply never applies.
+ */
+function targetsVerb(prelude, verb) {
+  const { verbs } = prelude;
+  if (verbs === 'all') return true;
+
+  const list = typeof verbs === 'string' ? [verbs] : verbs;
+  if (!Array.isArray(list) || list.length === 0 || list.some((entry) => typeof entry !== 'string')) {
+    throw new Error(`Boot prelude "${prelude.name}" declares no verbs: \`verbs\` is 'all', one verb name, or a list of verb names.`);
+  }
+
+  return verb !== null && list.includes(verb);
+}
+
+/**
+ * Run every prelude the verb selects, in list order.
+ *
+ * @param {object} [options]
+ * @param {string} [options.verb] - The verb about to run (the CLI's first positional).
+ * @param {string} [options.targetDir] - The invocation's directory (default: cwd).
+ * @param {string|null} [options.brandRoot] - The brand root; resolved from `targetDir` when absent.
+ * @param {object} [options.config] - The composed omega config, when the caller already has it.
+ * @param {Array<{ name: string, verbs: string|string[], run: function }>} [options.preludes] - The list (default: PRELUDES).
+ * @returns {{ ran: string[] }} The preludes that ran, in the order they ran.
+ */
+function runPreludes(options = {}) {
+  const preludes = options.preludes || PRELUDES;
+  const verb = normalizeVerb(options.verb);
+  const targetDir = options.targetDir || process.cwd();
+  const brandRoot = options.brandRoot === undefined ? resolveBrandRoot(targetDir) : options.brandRoot;
+
+  // Filtering first, and over the WHOLE list: a malformed `verbs` is raised
+  // before any prelude has run, not halfway through the boot.
+  const selected = preludes.filter((prelude) => targetsVerb(prelude, verb));
+  const ran = [];
+
+  for (const prelude of selected) {
+    try {
+      prelude.run({ verb, brandRoot, targetDir, config: options.config });
+    } catch (error) {
+      console.error(`omega: ${error.message}`);
+      process.exit(1);
+    }
+    ran.push(prelude.name);
+  }
+
+  return { ran };
+}
+
+/**
+ * The brand root of an invocation, or null outside a brand (this monorepo's own
+ * packages, a fresh directory). Required lazily: `@omega.js/config` is loaded by
+ * most verbs anyway, and a boot that resolves nothing should not pay for it.
+ *
+ * @param {string} targetDir - The invocation's directory.
+ * @returns {string|null}
+ */
+function resolveBrandRoot(targetDir) {
+  return require('../../config/index.js').resolveBrandRoot(targetDir);
+}
+
+module.exports = {
+  runPreludes,
+  PRELUDES,
+};

package/dist/vendor/devkit/preludes/origin-heal.js

@@ -0,0 +1,142 @@
+/**
+ * The origin heal: a brand whose `origin` names a repo GitHub has since
+ * redirected is pointed at the address GitHub answers with
+ * ([#890](https://github.com/Omega-JS-Stack/omega/issues/890)).
+ *
+ * A transfer or a rename leaves every clone pointing at the old address. Git
+ * follows GitHub's redirect and keeps working, so nothing ever complains, and
+ * the stale remote surfaces later as a push to a repo the brand no longer is
+ * (seen on the `omega-omega` transfer into `Omega-JS-Stack`, 2026-09-12).
+ *
+ * The REDIRECT is the authority, not the config: `gh api repos/<owner>/<name>`
+ * on the slug the checkout already carries follows GitHub's own 301 and answers
+ * the CURRENT `full_name`, so a brand is healed onto wherever its repo actually
+ * moved, config or no config. That costs one GitHub read per boot, which is the
+ * price of healing from the truth instead of from a typed value.
+ *
+ * The decision, in the order it is cheapest to answer:
+ *   - no brand root: nothing to compare, and not one read made;
+ *   - no `.git` AT the brand root: a no-op, never a walk up, and answered by one
+ *     stat before anything else is read. Git resolves a repo by walking up, and
+ *     a brand nested in another repo (a fixture brand inside this monorepo, a
+ *     target checked out under someone else's tree) would otherwise have the
+ *     ENCLOSING repo's remote read and rewritten;
+ *   - no `origin`, or an origin that is not a GitHub remote: a no-op. A
+ *     checkout nobody has pushed yet, and a brand hosted elsewhere, are
+ *     expected external conditions, not failures;
+ *   - a repo GitHub does not have (a 404: it is gone), or a GitHub it cannot
+ *     reach (offline, no `gh` auth): a silent no-op. Rewriting a remote on an
+ *     answer nobody got would take a working checkout and break it;
+ *   - GitHub answering the slug the remote already names (compared
+ *     case-insensitively, GitHub's own comparison): converged, silent;
+ *   - anything else: the remote is rewritten to the answered `full_name`,
+ *     keeping its own url form, and the heal is stated in one line.
+ *
+ * Then DRIFT, on whatever the answer was: the WHOLE slug GitHub answers against
+ * the source repo the config derives (`@omega.js/config`'s `repoDrift`, so a
+ * rename drifts as surely as a transfer,
+ * [#934](https://github.com/Omega-JS-Stack/omega/issues/934)), stated in one
+ * line and nothing more. Never fatal: this runs before every verb, and a fatal
+ * boot would lock out the verbs that fix the mismatch. The verbs that ACT on
+ * the derived repo (the manage walk, the deploy) refuse on the same line
+ * instead. The prelude never writes config: which of the two is wrong (the
+ * config, or where the repo lives) is a human's call.
+ *
+ * The WRITE is the one thing that fails loudly: a `git remote set-url` refused
+ * after a `get-url` just answered is not an external condition, it is a broken
+ * invariant, and the runner stops the boot on it.
+ */
+
+const { readOrigin, retargetRemoteUrl, setRemoteUrl } = require('../git-remote.js');
+const github = require('../github-repo.js');
+
+// The one network read runs on EVERY verb boot, so a network that hangs (a
+// captive portal, a dropped link) is bounded here and lands on the same silent
+// `unreachable` branch an offline machine does.
+const GITHUB_READ_TIMEOUT_MS = 10000;
+
+/**
+ * @param {object} context - The prelude context.
+ * @param {string|null} context.brandRoot - The brand root of the invocation.
+ * @param {object} [context.config] - The composed omega config, when the caller has it.
+ * @param {function} [context.execFn] - Injectable git exec (tests).
+ * @param {function} [context.resolveRepo] - Injectable `(owner, name) => repo|null` (tests).
+ * @param {function} [context.log] - Injectable line printer (tests).
+ * @returns {{ healed: boolean, reason?: string, from?: string, to?: string, drift?: { origin: string, derived: string } }}
+ */
+function run(context = {}) {
+  const { brandRoot, execFn } = context;
+  const log = context.log || console.log;
+  // Called through the module so the ONE network read has a seam a real CLI
+  // boot can stub too (the integration test patches it here).
+  const resolveRepo = context.resolveRepo || ((owner, name) => github.getRepo(owner, name, { timeout: GITHUB_READ_TIMEOUT_MS }));
+
+  if (!brandRoot) return { healed: false, reason: 'no-brand' };
+
+  // One stat before anything else (most boots in this monorepo's own trees and
+  // in every fixture brand end there), then the remote itself.
+  const current = readOrigin({ dir: brandRoot, execFn });
+  if (!current.slug) return { healed: false, reason: current.reason };
+
+  const { url, slug: from } = current;
+
+  // The ONE network read, on the slug the checkout carries: GitHub follows its
+  // own redirect and names where that repo lives now.
+  let resolved;
+  try {
+    resolved = resolveRepo(current.owner, current.repo);
+  } catch (e) {
+    return { healed: false, reason: 'unreachable' };
+  }
+  if (!resolved) return { healed: false, reason: 'missing' };
+
+  const to = resolved.full_name;
+  let result;
+
+  if (to.toLowerCase() === from.toLowerCase()) {
+    result = { healed: false, reason: 'converged' };
+  } else {
+    setRemoteUrl({ dir: brandRoot, url: retargetRemoteUrl(url, to), execFn });
+    log(`omega: origin healed from ${from} to ${to}`);
+    result = { healed: true, from, to };
+  }
+
+  const config = composedConfig(brandRoot, context.config);
+  const { repoDrift, sourceRepo } = require('../../config/index.js');
+  const drift = config ? repoDrift(to, config) : null;
+
+  if (drift) {
+    log(`omega: ${drift}`);
+    result.drift = { origin: to, derived: sourceRepo(config).slug };
+  }
+
+  return result;
+}
+
+/**
+ * The composed config the drift is read against: the caller's when it has one,
+ * else loaded here, and an unloadable one answers null ("no drift"): a config
+ * the boot cannot read is the VERB's failure to report, in its own words, never
+ * a prelude's.
+ *
+ * @param {string} brandRoot - The brand root.
+ * @param {object} [config] - The composed config, when the caller has it.
+ * @returns {object|null}
+ */
+function composedConfig(brandRoot, config) {
+  if (config) return config;
+
+  const { loadConfig } = require('../../config/index.js');
+
+  try {
+    return loadConfig(brandRoot).config;
+  } catch (e) {
+    return null;
+  }
+}
+
+module.exports = {
+  name: 'origin-heal',
+  verbs: 'all',
+  run,
+};

package/dist/vendor/devkit/service-account.js

@@ -0,0 +1,43 @@
+/**
+ * The Firebase service-account key's ONE lookup
+ * ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)), and the ONE
+ * spelling of every path under the brand's secrets folder
+ * ([#897](https://github.com/Omega-JS-Stack/omega/issues/897)).
+ *
+ * The key is a FILE the cloud manage service mints, never a `.env` value, so
+ * everything that needs it (the backend stage, the deploy-roles read, the
+ * secrets publish that sends it to a runner) resolves the same two candidates
+ * in the same order: the target root's own, then the brand's secrets folder.
+ * It lived in the backend's stage helper while the backend was its only reader;
+ * the shared secrets publisher reads it now, and devkit never requires a
+ * framework, so the lookup lives here and the backend imports it.
+ *
+ * The Google OAuth client the authentication service writes obeys the same
+ * folder rule, so it is named here too: a rename of the folder is one edit,
+ * not a hunt through every manager and backend reader.
+ */
+const path = require('node:path');
+const jetpack = require('fs-jetpack');
+const { findBrandRoot } = require('../config/index.js');
+
+// The brand-level home of every minted credential, and the two files in it.
+const SECRETS_DIR = path.join('.omega', 'secrets');
+const SERVICE_ACCOUNT_REL = path.join(SECRETS_DIR, 'service-account.json');
+const GOOGLE_OAUTH_REL = path.join(SECRETS_DIR, 'google-oauth.json');
+
+/**
+ * The service-account key a target deploys with, or null when none is minted.
+ *
+ * @param {string} projectDir - The target root.
+ * @returns {string|null} Absolute path to the key file.
+ */
+function resolveServiceAccountPath(projectDir) {
+  const brandRoot = findBrandRoot(projectDir);
+
+  return [
+    path.join(projectDir, 'service-account.json'),
+    brandRoot ? path.join(brandRoot, SERVICE_ACCOUNT_REL) : null,
+  ].filter(Boolean).find((candidate) => jetpack.exists(candidate)) || null;
+}
+
+module.exports = { resolveServiceAccountPath, SECRETS_DIR, SERVICE_ACCOUNT_REL, GOOGLE_OAUTH_REL };