@omega.js/manager 0.1.0

package/dist/services/testing/lib/checks.js

@@ -0,0 +1,467 @@
+/**
+ * Health-check implementations for the testing service — omega-manager's
+ * target-checks helpers rebuilt for brand monorepos. Local checks read the
+ * repo; live checks fetch the deployed site/API and shell out to npm/gh.
+ *
+ * Every check records into a shared recorder whose results shape matches
+ * RunSummary's drill-down: passed = [name], warned = [{ name, warning }],
+ * failed = [{ name, error }]. Dim notes and dry-run "would" lines are
+ * display-only — they never enter the results.
+ *
+ * Injection seams (all via context.options — they ride runManage options so
+ * the full-loop tests stay network-free): options.fetch, options.exec,
+ * options.retryDelayMs.
+ */
+
+const fs = require('node:fs');
+const { execSync } = require('node:child_process');
+const path = require('node:path');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+
+const { TARGET_FRAMEWORKS } = require('../../../config.js');
+const { brandRepo, brandRepoName, instanceIdFromDirName, resolveInstanceUrl } = require('../../../vendor/config/index.js');
+const { recordDeploy, readDeployRecord } = require('../../../vendor/devkit/deploy-record.js');
+
+const MAX_RETRIES = 3;
+const MAX_FILES_SHOWN = 10;
+
+// Mirrors @omega.js/backend: getApiUrl() serves from the `api.` subdomain and
+// mounts its routes under /omega (packages/backend route prefix)
+const API_SUBDOMAIN = 'api';
+const API_HEALTH_PATH = '/omega/health';
+
+const FETCH_HEADERS = {
+  'Cache-Control': 'no-cache, no-store, must-revalidate',
+  'Pragma': 'no-cache',
+  'User-Agent': 'OmegaManager/1.0 HealthCheck',
+};
+
+/**
+ * Create the shared check recorder. Prints each check as it lands and
+ * accumulates the results arrays the handler returns.
+ *
+ * @returns {Object} - { pass, warn, fail, note, would, results, counts }
+ */
+function createRecorder() {
+  const passed = [];
+  const warned = [];
+  const failed = [];
+
+  return {
+    pass(name, detail) {
+      passed.push(name);
+      console.log(`      ${chalk.green('✓')} ${name}${detail ? chalk.dim(`: ${detail}`) : ''}`);
+    },
+    warn(name, warning) {
+      warned.push({ name, warning });
+      console.log(`      ${chalk.yellow('⚠')} ${name}${warning ? `: ${chalk.yellow(warning)}` : ''}`);
+    },
+    fail(name, error) {
+      failed.push({ name, error });
+      console.log(`      ${chalk.red('✗')} ${name}${error ? `: ${chalk.red(error)}` : ''}`);
+    },
+    // Display-only informational line (check not applicable / not verifiable)
+    note(name, detail) {
+      console.log(`      ${chalk.dim(`– ${name}${detail ? `: ${detail}` : ''}`)}`);
+    },
+    // Display-only dry-run line for a skipped remote action
+    would(action) {
+      console.log(`      ${chalk.yellow('⊘')} would ${action} ${chalk.dim('[DRY RUN]')}`);
+    },
+    results() {
+      return { passed, warned, failed };
+    },
+    counts() {
+      return { passed: passed.length, warned: warned.length, failed: failed.length };
+    },
+  };
+}
+
+/**
+ * Default exec — thin execSync wrapper so tests can inject a recording fake
+ * with the same (command, options) → stdout surface.
+ */
+function defaultExec(command, options = {}) {
+  return execSync(command, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], ...options });
+}
+
+/**
+ * Fetch with retry — retries network errors AND non-2xx/3xx statuses with a
+ * linear backoff (delayMs, 2×delayMs, …), returning the last response either
+ * way. Success (2xx/3xx) returns immediately.
+ *
+ * @param {Object} ctx - Check context ({ fetchImpl, retryDelayMs })
+ * @param {string} url - URL to fetch
+ * @returns {Object} - { response, duration } or { error } after all retries
+ */
+async function fetchWithRetry(ctx, url) {
+  let last = { error: 'unreachable' };
+
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      const start = Date.now();
+      const response = await ctx.fetchImpl(url, { headers: FETCH_HEADERS, redirect: 'follow' });
+      last = { response, duration: Date.now() - start };
+
+      if (response.status >= 200 && response.status < 400) {
+        return last;
+      }
+    } catch (error) {
+      // Node's fetch wraps network errors ("fetch failed") — the cause has
+      // the useful message (getaddrinfo ENOTFOUND, ECONNREFUSED, …)
+      last = { error: error.cause?.message || error.message };
+    }
+
+    if (attempt < MAX_RETRIES) {
+      await new Promise((resolve) => setTimeout(resolve, ctx.retryDelayMs * attempt));
+    }
+  }
+
+  return last;
+}
+
+/**
+ * npm latest version of a package, cached per run. null when the registry
+ * lookup fails (unpublished package, offline) — callers dim out, never warn.
+ */
+function getLatestVersion(ctx, packageName) {
+  if (!(packageName in ctx.versionCache)) {
+    try {
+      ctx.versionCache[packageName] = ctx.exec(`npm view ${packageName} version`).trim();
+    } catch {
+      ctx.versionCache[packageName] = null;
+    }
+  }
+  return ctx.versionCache[packageName];
+}
+
+/**
+ * Compare two x.y.z versions numerically. -1 / 0 / 1.
+ */
+function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Resolve the INSTALLED version of a package via the node_modules climb from
+ * a directory — handles file:/workspace refs where the declared range says
+ * nothing. null when not installed.
+ */
+function installedVersion(fromDir, packageName) {
+  let dir = path.resolve(fromDir);
+
+  while (true) {
+    const pkg = jetpack.read(path.join(dir, 'node_modules', packageName, 'package.json'), 'json');
+    if (pkg?.version) {
+      return pkg.version;
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// ── Local checks ────────────────────────────────────────────────────────────
+
+/**
+ * Per-target file checks: package.json parses; web targets produced a build;
+ * backend targets have their Firebase scaffolding.
+ */
+function checkTargetFiles(recorder, entry) {
+  const pkg = jetpack.read(path.join(entry.path, 'package.json'), 'json');
+  if (pkg) {
+    recorder.pass(`${entry.name}: package.json`);
+  } else {
+    recorder.fail(`${entry.name}: package.json`, 'missing or unparseable');
+  }
+
+  if (entry.target === 'web') {
+    if (fs.existsSync(path.join(entry.path, 'dist', 'index.html'))) {
+      recorder.pass(`${entry.name}: build output`);
+    } else {
+      recorder.fail(`${entry.name}: build output`, 'dist/index.html missing — run the update service');
+    }
+  }
+
+  if (entry.target === 'backend') {
+    // A custom-server backend (#584) deploys no Cloud Functions, so it has no
+    // firebase.json to carry — the ONE Firebase-only check here, noted rather
+    // than failed. The staged build below is checked in both modes.
+    if (entry.projectType === 'custom') {
+      recorder.note(`${entry.name}: firebase.json`, "skipped — projectType: 'custom' deploys no Cloud Functions");
+    } else if (fs.existsSync(path.join(entry.path, 'firebase.json'))) {
+      recorder.pass(`${entry.name}: firebase.json`);
+    } else {
+      recorder.fail(`${entry.name}: firebase.json`, 'missing');
+    }
+    // Staged output (src/dist pillar) — the backend's build-output twin of
+    // web's dist/index.html check
+    if (fs.existsSync(path.join(entry.path, 'dist', 'package.json'))) {
+      recorder.pass(`${entry.name}: staged dist/`);
+    } else {
+      recorder.fail(`${entry.name}: staged dist/`, 'dist/package.json missing — run the update service (omega build)');
+    }
+  }
+}
+
+/**
+ * Framework version check: the target's installed framework package vs the npm
+ * latest. Silent when the target doesn't declare its framework;
+ * dims out when the registry lookup fails (e.g. package not published yet).
+ */
+function checkFrameworkVersion(recorder, entry, ctx) {
+  const framework = TARGET_FRAMEWORKS[entry.target];
+  if (!framework) return;
+
+  // Deps live on the ONE manifest per target (src/dist pillar)
+  const pkgDir = entry.path;
+  const pkg = jetpack.read(path.join(pkgDir, 'package.json'), 'json');
+  const declared = pkg?.dependencies?.[framework] || pkg?.devDependencies?.[framework];
+  if (!declared) return;
+
+  const installed = installedVersion(pkgDir, framework) || declared.replace(/^[\^~>=<]+/, '');
+  const name = `${entry.name}: ${framework}`;
+
+  if (!/^\d/.test(installed)) {
+    recorder.note(name, `${installed} (not installed — run the update service)`);
+    return;
+  }
+
+  if (ctx.dryRun) {
+    recorder.would(`npm view ${framework} version`);
+    return;
+  }
+
+  const latest = getLatestVersion(ctx, framework);
+
+  if (!latest) {
+    recorder.note(name, `${installed} (could not check latest)`);
+  } else if (compareVersions(installed, latest) >= 0) {
+    recorder.pass(name, `${installed} (latest: ${latest})`);
+  } else {
+    recorder.warn(name, `outdated (${installed} → ${latest})`);
+  }
+}
+
+/**
+ * Parse `git status --porcelain` output into { status, file } entries.
+ * Lines must NOT be trimmed before slicing — the two status columns can
+ * legitimately start with a space (` M path`), so a leading trim shifts
+ * the path offset and eats the first character.
+ * @param {string} stdout - raw porcelain output
+ * @returns {Array<{ status: string, file: string }>}
+ */
+function parseWorkingTree(stdout) {
+  return stdout.split('\n').filter((line) => line.trim()).map((line) => ({
+    status: line.substring(0, 2).trim(),
+    file: line.substring(3),
+  }));
+}
+
+/**
+ * Working tree check — uncommitted files under the brand root (scoped with
+ * `-- .` so a brand nested in a larger workspace only sees its own files).
+ * Silent when the brand isn't in a git repository.
+ */
+function checkWorkingTree(recorder, ctx) {
+  let stdout;
+  try {
+    stdout = ctx.exec('git status --porcelain -- .', { cwd: ctx.brandRoot });
+  } catch {
+    return;
+  }
+
+  const files = parseWorkingTree(stdout);
+
+  if (files.length === 0) {
+    recorder.pass('working tree', 'clean');
+    return;
+  }
+
+  recorder.warn('working tree', `${files.length} uncommitted file${files.length === 1 ? '' : 's'}`);
+  for (const { status, file } of files.slice(0, MAX_FILES_SHOWN)) {
+    console.log(`        ${chalk.dim(status)} ${chalk.dim(file)}`);
+  }
+  if (files.length > MAX_FILES_SHOWN) {
+    console.log(`        ${chalk.dim(`... and ${files.length - MAX_FILES_SHOWN} more`)}`);
+  }
+}
+
+// ── Live checks ─────────────────────────────────────────────────────────────
+
+/**
+ * Homepage check — the deployed site answers on ITS instance's URL: the
+ * instance entry's url (multi-instance targets), else the id AS a subdomain of
+ * the brand host (#588), falling back to the brand URL for the single-instance
+ * world. Deploy records key per instance too, so a never-deployed admin
+ * instance nudges without failing a live main.
+ */
+async function checkHomepage(recorder, entry, ctx) {
+  const instance = instanceIdFromDirName(entry.name, entry.target);
+  const url = resolveInstanceUrl(ctx.brandConfig.targets?.[entry.target], instance, ctx.brandConfig);
+  const name = `${entry.name}: homepage`;
+
+  if (!url) {
+    recorder.warn(name, 'no brand.url configured — cannot check');
+    return;
+  }
+
+  if (ctx.dryRun) {
+    recorder.would(`fetch ${url}`);
+    return;
+  }
+
+  // No deploy record → a live miss means "not deployed yet", not an outage
+  // (never-deployed vs deployed-but-down — Ian 2026-07-17). A live HIT on a
+  // record-less brand adopts: the record is per-machine, so fresh clones of
+  // deployed brands self-heal here.
+  const deployed = readDeployRecord({ dir: ctx.brandRoot, target: entry.target, instance });
+  const { response, duration, error } = await fetchWithRetry(ctx, url);
+  const live = !error && response.status >= 200 && response.status < 400;
+
+  if (live) {
+    recorder.pass(name, `${url} → ${response.status} (${duration}ms)`);
+    if (!deployed) {
+      recordDeploy({ dir: ctx.brandRoot, target: entry.target, instance, detail: { adopted: true } });
+    }
+  } else if (!deployed) {
+    recorder.warn(name, `not deployed yet — run \`omega deploy\` when ready (${url})`);
+  } else {
+    recorder.fail(name, `${url} → ${error || response.status}`);
+  }
+}
+
+/**
+ * API health check — the deployed backend answers on
+ * https://api.{host}{API_HEALTH_PATH}, plus a deployed-version comparison
+ * from the health payload. Skipped for shared Firebase projects (the owning
+ * brand deploys the backend).
+ */
+async function checkApiHealth(recorder, entry, ctx) {
+  const name = `${entry.name}: API health`;
+
+  if (ctx.brandConfig.cloud?.shared === true) {
+    recorder.note(name, 'shared Firebase project (owning brand deploys the backend)');
+    return;
+  }
+
+  const baseUrl = ctx.brandConfig.brand?.url;
+  if (!baseUrl) {
+    recorder.warn(name, 'no brand.url configured — cannot check');
+    return;
+  }
+
+  const host = baseUrl.replace(/^https?:\/\//, '');
+  const apiUrl = `https://${API_SUBDOMAIN}.${host}${API_HEALTH_PATH}`;
+
+  if (ctx.dryRun) {
+    recorder.would(`fetch ${apiUrl}`);
+    return;
+  }
+
+  // Same never-deployed vs deployed-but-down split as checkHomepage
+  const deployRecord = readDeployRecord({ dir: ctx.brandRoot, target: entry.target });
+  const { response, duration, error } = await fetchWithRetry(ctx, apiUrl);
+  const live = !error && response.status >= 200 && response.status < 400;
+
+  if (!live) {
+    if (!deployRecord) {
+      recorder.warn(name, `not deployed yet — run \`omega deploy\` when ready (${apiUrl})`);
+    } else {
+      recorder.fail(name, `${apiUrl} → ${error || response.status}`);
+    }
+    return;
+  }
+
+  recorder.pass(name, `${apiUrl} → ${response.status} (${duration}ms)`);
+  if (!deployRecord) {
+    recordDeploy({ dir: ctx.brandRoot, target: entry.target, detail: { adopted: true } });
+  }
+
+  // Deployed-version comparison from the health payload
+  let data = null;
+  try {
+    data = await response.json();
+  } catch {
+    return;
+  }
+
+  const framework = TARGET_FRAMEWORKS[entry.target];
+  const deployed = data?.backendVersion;
+  if (!deployed) return;
+
+  const deployedName = `${entry.name}: deployed backend`;
+  const latest = getLatestVersion(ctx, framework);
+
+  if (!latest) {
+    recorder.note(deployedName, `${deployed} (could not check latest)`);
+  } else if (deployed === latest) {
+    recorder.pass(deployedName, `${deployed} (up to date)`);
+  } else {
+    recorder.warn(deployedName, `outdated (${deployed} → ${latest})`);
+  }
+}
+
+/**
+ * GitHub Actions check — latest workflow run of the brand repo. Silent when
+ * no repo.providers.github.org is configured (the github service already reports that skip)
+ * or when the gh CLI is unavailable.
+ */
+function checkGitHubActions(recorder, ctx) {
+  const github = ctx.brandConfig.repo?.providers?.github || {};
+  if (!github.org) return;
+
+  // BOTH halves from the one derivation (an `owner/name` slug owns itself); the
+  // service's own brand id stands in for a config that names no brand.
+  const repo = brandRepo(ctx.brandConfig).repo || `${github.org}/${brandRepoName({ brand: { id: ctx.brandId } })}`;
+
+  if (ctx.dryRun) {
+    recorder.would(`gh run list --repo ${repo}`);
+    return;
+  }
+
+  let runs;
+  try {
+    runs = JSON.parse(ctx.exec(`gh run list --repo ${repo} --limit 1 --json status,conclusion,name`));
+  } catch {
+    recorder.note('GitHub Actions', 'could not check (gh unavailable or no access)');
+    return;
+  }
+
+  if (!runs.length) {
+    recorder.note('GitHub Actions', 'no runs found');
+    return;
+  }
+
+  const run = runs[0];
+  if (run.status === 'completed' && run.conclusion === 'success') {
+    recorder.pass('GitHub Actions', `${run.name} → success`);
+  } else if (run.status === 'in_progress') {
+    recorder.warn('GitHub Actions', `${run.name} → in progress`);
+  } else {
+    recorder.fail('GitHub Actions', `${run.name} → ${run.conclusion || run.status}`);
+  }
+}
+
+module.exports = {
+  createRecorder,
+  defaultExec,
+  fetchWithRetry,
+  compareVersions,
+  installedVersion,
+  parseWorkingTree,
+  checkTargetFiles,
+  checkFrameworkVersion,
+  checkWorkingTree,
+  checkHomepage,
+  checkApiHealth,
+  checkGitHubActions,
+};

package/dist/services/update/index.js

@@ -0,0 +1,20 @@
+/**
+ * Update service — installs dependencies and builds every target in the brand
+ * monorepo. The monorepo cousin of omega-manager's update service (which
+ * walks separate per-target repos); phases beyond install/build (bump,
+ * deploy, sync) port over with their flags as the cutover advances.
+ */
+const { createServiceRunner } = require('../../lib/service-runner.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: (context) => {
+    const targets = (context.targets || []).filter((entry) => entry.target);
+
+    if (targets.length === 0) {
+      return { skip: true, reason: 'no target-mapped dirs' };
+    }
+
+    return {};
+  },
+});

package/dist/services/update/lib/cache.js

@@ -0,0 +1,59 @@
+/**
+ * The update service's incremental cache (#445) — `.omega/cache/update.json`
+ * at the brand root: per target, the two fingerprints its last successful build
+ * ran against. Derived data, so it lives with the brand's other caches under
+ * `.omega/cache/` (the edge service's read cache is its neighbour) — never in
+ * config, which holds provisioned facts.
+ *
+ * Missing, unparseable, or written in an older shape → an empty cache, which
+ * reads as "every target is fresh": the run does the full update and rewrites the
+ * file. A cache is an optimization, never a reason to fail the walk, so a
+ * failed write warns and the walk continues.
+ */
+const { join } = require('node:path');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+
+const CACHE_VERSION = 2; // v2: the per-target map key renamed apps -> targets (#455)
+
+/**
+ * @param {string} brandRoot - The brand monorepo root.
+ * @returns {string} Absolute path to the cache file.
+ */
+function cacheFile(brandRoot) {
+  return join(brandRoot, '.omega', 'cache', 'update.json');
+}
+
+/**
+ * @param {string} brandRoot - The brand monorepo root.
+ * @returns {{ version: number, targets: Object }} The cache, or an empty one.
+ */
+function readCache(brandRoot) {
+  let data = null;
+
+  try {
+    data = jetpack.read(cacheFile(brandRoot), 'json');
+  } catch {
+    data = null;
+  }
+
+  if (data?.version !== CACHE_VERSION || typeof data.targets !== 'object' || data.targets === null) {
+    return { version: CACHE_VERSION, targets: {} };
+  }
+
+  return data;
+}
+
+/**
+ * @param {string} brandRoot - The brand monorepo root.
+ * @param {Object} cache - The cache to persist.
+ */
+function writeCache(brandRoot, cache) {
+  try {
+    jetpack.write(cacheFile(brandRoot), cache);
+  } catch (error) {
+    console.log(`      ${chalk.yellow('⚠')} update cache not written${chalk.dim(`: ${error.message}`)}`);
+  }
+}
+
+module.exports = { readCache, writeCache, cacheFile, CACHE_VERSION };

package/dist/services/update/lib/fingerprint.js

@@ -0,0 +1,157 @@
+/**
+ * Update fingerprints (#445) — the two input sets that decide whether a target
+ * still needs its build, each hashed to one string:
+ *
+ *   files      — a sweep of the target's own tree (relative path + size + mtime
+ *                per file): the assets service's mtime-diff precedent scaled
+ *                from a file to a directory. Installed deps, build output,
+ *                logs and the machinery dirs are excluded, so a build never
+ *                re-dirties its own inputs. The merge-chain files ABOVE the
+ *                target (brand and company omega.json5 + .env) fold in too —
+ *                the build reads them, and a brand-config edit that left every
+ *                target "converged" would serve stale output silently.
+ *   frameworks — every declared `@omega.js/*` dependency's installed identity:
+ *                the version string for an npm install, and for a LOCAL LINK
+ *                (which points into the monorepo, where the version stands
+ *                still between builds) the link target's version plus a sweep
+ *                of its build output.
+ *
+ * Both are stat walks — no file contents are ever read.
+ */
+const { createHash } = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const jetpack = require('fs-jetpack');
+
+// Never part of a target's input set: installed deps (node_modules), build
+// output (dist), run logs (logs), and the machinery `omega build` / `omega
+// dev` / firebase write beside the sources (.temp, .omega, .cache, .firebase).
+const EXCLUDED_DIRS = new Set(['node_modules', 'dist', 'logs', '.temp', '.omega', '.cache', '.firebase', '.git']);
+
+/**
+ * Hash a directory tree by path + size + mtime. Entries are walked in name
+ * order so the digest is machine-independent; anything that is neither a
+ * plain file nor a directory (symlinks, sockets) is skipped, as are debug
+ * logs and .DS_Store — churn that says nothing about the sources.
+ *
+ * @param {string} dir - Directory to sweep.
+ * @returns {string|null} Hex digest, or null when the directory doesn't exist.
+ */
+function sweep(dir) {
+  if (!jetpack.exists(dir)) {
+    return null;
+  }
+
+  const hash = createHash('sha1');
+
+  const walk = (current, prefix) => {
+    const entries = fs.readdirSync(current, { withFileTypes: true })
+      .sort((a, b) => (a.name < b.name ? -1 : 1));
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!EXCLUDED_DIRS.has(entry.name)) {
+          walk(path.join(current, entry.name), `${prefix}${entry.name}/`);
+        }
+        continue;
+      }
+
+      if (!entry.isFile() || entry.name.endsWith('.log') || entry.name === '.DS_Store') {
+        continue;
+      }
+
+      const stat = fs.statSync(path.join(current, entry.name));
+      hash.update(`${prefix}${entry.name}:${stat.size}:${stat.mtimeMs}\n`);
+    }
+  };
+
+  walk(dir, '');
+  return hash.digest('hex');
+}
+
+/**
+ * Where does `name` resolve from `fromDir` via the node_modules climb? A
+ * manual walk (not require.resolve) so exports-restricted packages and
+ * bin-only packages don't false-negative.
+ *
+ * @param {string} fromDir - Directory to climb from.
+ * @param {string} name - Package name.
+ * @returns {string|null} The package directory, or null when it doesn't resolve.
+ */
+function resolvePackageDir(fromDir, name) {
+  let dir = path.resolve(fromDir);
+
+  while (true) {
+    const candidate = path.join(dir, 'node_modules', name);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Hash the installed identity of every `@omega.js/*` package the target declares.
+ *
+ * @param {string} targetPath - The target root.
+ * @returns {string} Hex digest.
+ */
+function frameworkFingerprint(targetPath) {
+  const pkg = jetpack.read(path.join(targetPath, 'package.json'), 'json');
+  const declared = Object.keys({ ...pkg?.dependencies, ...pkg?.devDependencies })
+    .filter((name) => name.startsWith('@omega.js/'))
+    .sort();
+
+  const parts = declared.map((name) => {
+    const dir = resolvePackageDir(targetPath, name);
+    if (!dir) {
+      return `${name}@missing`;
+    }
+
+    const version = jetpack.read(path.join(dir, 'package.json'), 'json')?.version || 'unknown';
+    if (!fs.lstatSync(dir).isSymbolicLink()) {
+      return `${name}@${version}`;
+    }
+
+    // A local link resolves into the monorepo: the version never moves there,
+    // so the link target's build output is what actually changes under the target.
+    const target = fs.realpathSync(dir);
+    return `${name}@${version}#${sweep(path.join(target, 'dist')) || 'no-dist'}`;
+  });
+
+  return createHash('sha1').update(parts.join('\n')).digest('hex');
+}
+
+/**
+ * The pair of fingerprints cached per target.
+ *
+ * Chain entries are labelled (not path-keyed) so the digest survives a brand
+ * directory move the way the sweep's relative paths do; an absent file hashes
+ * as absent, so growing a .env later dirties the fingerprint like an edit.
+ *
+ * @param {string} targetPath - The target root.
+ * @param {Array<{ label: string, file: string }>} [chainFiles] - Merge-chain
+ *   files outside the target tree that its build reads (brand/company config
+ *   and .env).
+ * @returns {{ files: string, frameworks: string }}
+ */
+function fingerprintTarget(targetPath, chainFiles = []) {
+  const chain = chainFiles.map(({ label, file }) => {
+    const stat = fs.statSync(file, { throwIfNoEntry: false });
+    return stat ? `${label}:${stat.size}:${stat.mtimeMs}` : `${label}:absent`;
+  });
+
+  const files = createHash('sha1')
+    .update([sweep(targetPath) || 'missing', ...chain].join('\n'))
+    .digest('hex');
+
+  return {
+    files,
+    frameworks: frameworkFingerprint(targetPath),
+  };
+}
+
+module.exports = { fingerprintTarget, resolvePackageDir, sweep, EXCLUDED_DIRS };